2

By recently I mean some weeks ago. I am trying to continue a project I left 2 weeks ago and I need time to understand some functions I wrote (not copied from somewhere) and it takes me time. Normally I don't need to because my functions, methods etc. are black boxes but when I need to change something it's really hard. Does this mean I write bad code? I am still in school and I am the only who writes/uses the code so I don't have feedback, but I am afraid that if it is difficult for me to understand it, it would be 10 times more difficult for someone else. What should I do? I write a lot of comments but most of the time are useless when reviewing.

Do you have any suggestions?

3
  • 2
    Have you read the book clean code? And as a rule of thumb, comments in the middle of the code usually point to poor code (and missing method and classes).
    – Augusto
    May 27, 2014 at 0:52
  • Don't comment just for the sake of commenting. Good code should be 99% self documenting. engine.Start() says a lot more than a.b(). The good news is, you see this problem early on, and can fix it. Some "programmers" I know still don't get it.
    – Jay
    May 27, 2014 at 4:21
  • it does not mean you write bad code, all you need is to strictly follow the habit of adding docString to functions you wrote and add comments wherever possible. May 27, 2014 at 7:00

4 Answers 4

3

It is normal, but there are proven counter-measures.

Train yourself to document all your non-throwaway code as if you were publishing it for other skilled programmers (but not for dummies). Do it as you write the code, part of the process; review it as you change the code. You will be pretty much another programmer when you've left it alone for, say, your summer holiday.

When you form a habit of this, it doesn't feel like a drag.

Documenting your code is a key weapon of design, problem-solving and bug-detecting. When you can't code it right, stop trying and document it first. If the code smells, document it and you will probably see where the smell comes from.

Then progress to documenting it first anyway.

Write code that is sufficiently well designed and modularized that the documentation of the interfaces is almost all the documentation you need to write: functions, templates, classes, methods; parameters and return values; pre-conditions and post-conditions; exceptions.

You want the implementation of an interface to be surveyable in one "eyeful" and "obvious" to skilled programmers. If you find the need to explain an implemention by a running commentary of comments, then the design and/or the implementation is bad. Smart-ass implementations always need explanation and are rarely worthwhile.

If you have some code you have written that you struggle to understand every time you need to maintain it, consider that a bug that needs fixed, and fix it at least by the Fixes Before Features principle.

2

It's "normal" for some definition of normal, but it's also something you should seek to improve.

I define my progress as a good programmer in terms of exactly that: how easily I understand my code when I look at it later ... and to some extent, how much I apologize in comments to my future self because I know it will be hard to understand (legacy code is sad).

Usually I write very few comments in code I write, since I believe that the code should be fairly obvious. The few comments I do write are to help the understanding of myself or anyone else who looks at the codebase (though that latter is not nearly as important as the first; anyone new will need a long time to become as intimate with the codebase as you are).

As an immediate path forward, I suggest that you delete all comments in that codebase, and then add comments until you understand, then look at how your new comments compare to your old ones.

2

Sometimes it is unavoidable but readability is one of the most important factors in the maintainability of a code base. You can get away with code that only you understand on tiny projects with tiny teams, but that doesn't scale well at all. Think high level, what does the code need to achieve? It needs to work and it needs to be maintainable(except for some rare cases).

Some things to consider...

  • If you have trouble reading your code a few days later, how are other team members going to be able to read it?
  • When someone has to make changes to that code 6 months later will the original author's intent be clear? If not, how can one be sure that any changes won't have unintended consequences that cascade throughout the whole system?(tests help mitigate this)
  • Well written code should prioritize readability(and resulting maintainability) over finding that neat one-line ultra-concise solution to a problem, which no-one except yourself will understand.
  • The vast majority of the code shouldn't need comments. The code IS the comments. Developers read/write code, so they shouldn't need them IF the code was written well (except for areas where complexity is unavoidable)
  • We as developers have limited resources in terms of our focus and brain power. Comments frequently serve as noise and can be problematic due to the ambiguous nature of many technical terms and how people understand them.
  • Leverage peer review. Before you check that code in, have another developer give it a once-over and see if they understand it. In practice it takes a lot of discipline to do this all the time, so often its best to adopt this as a team policy.

Now most of this may not appear to be applicable since you are still in school and all too often developing code for a course in no way resembles how things work in the real world; but you can still apply many of these concepts... e.g. use your professor to do peer review(his opinion is the only thing that matters in the end anyway right?)

1

Working on thing without other developer feedback can be really hard. Feedback helps us learn and grow much quicker. I work for a very small company, there are two of us, typically working on separate segments of projects, UI vs. back-end calculation logic. The internet provides lots of information, but this has to be broken down into applied knowledge, and the transition can be tough. Hence, sites like this are great for you and I.

The complexity of the code you write can be reduced. There are several ways to do this. One is by trying to break complex functions down into smaller functions. Try to use method names that describe clearly what the method is doing. For example, instead of a method named CalcMatDen, name it CalculateMaterialDensity. If you do this, one large function will suddenly become a series of calls to smaller more focused functions. Now when reading the code you can easily see what a large function does, and you can go directly to the level of complexity you care about...

Another thing you can do is write a method that returns a bool to replace complex if statements.

Instead of:

 if (depth > wellSurveyDepth && 
      depth > wellGeometryDepth && 
      depth > wellTemperatures)

Try writing a method so you can do something like this:

if (DepthExceedsWellDepths(depth))

If you have access to Pluralsight there is a great course called Clean Code: Writing Code for Humans by Corey House. Also the book Clean Code by Robert C. Martin may help. On a side note, writing Unit Tests can be very helpful when working toward writing more maintainable code.

Not the answer you're looking for? Browse other questions tagged or ask your own question.