Good code self-documents, however typically feedback are vital to serving to builders perceive why you wrote code a sure means.
Must you add feedback to your code or not? The reply, after all, is sure. It is also no. Or, much less facetiously, “You need to first try to make your code so simple as potential to know with out counting on feedback as a crutch. Solely on the level the place the code can not be made simpler to know do you have to start so as to add feedback.” Jeff Atwood penned that again in 2006, nevertheless it’s as related at the moment because it was again then. Maybe extra so.
SEE: Learn how to construct a profitable developer profession (free PDF) (TechRepublic)
The case towards feedback
Deliver up the subject and invariably (and shortly) somebody will let you know why you should not muddle your code with feedback. One of many major complaints about feedback is that they add noise to the code’s sign. “Good code is self-documenting,” the saying goes, and including feedback can typically serve to masks unhealthy code, and never for the higher. As Bennett Garner has written:
Over-commented code is commonly extra obscure than code with out feedback. Little notes forwards and backwards from all of the completely different maintainers of a challenge can typically get cluttered. You spend extra time studying the feedback than you do the precise code. And infrequently, you might have understood how this system works with out the feedback altogether.
That is unhealthy sufficient, however the issue compounds as feedback age. As Marco Bresciani has argued, “Do not imagine in feedback: they’re by no means up to date. Solely the code tells the reality.” Feedback might have been helpful sooner or later, however as code modifications (and that is frequent), the feedback typically do not. This leaves the code cluttered with outdated feedback that might find yourself complicated fairly than clarifying.” Ideally builders would replace their feedback when updating the code, however this tends to not occur.
In fact, most code editors assist code folding, which hides the feedback and permits builders to simply take a look at the supply code. However this assumes feedback are at all times unhealthy, which is not true. When may they be warranted?
The case for feedback
Attempt as a lot as you may to make your code “self-documenting,” one factor code cannot do: Clarify the why behind the code. As Jef Raskin has famous, “[T]he basic purpose code can not ever be self-documenting and automated documentation turbines cannot create what is required is that they can not clarify why this system is being written, and the rationale for selecting this or that technique. They can not focus on the explanations sure different approaches have been taken.” You may, for instance, want to elucidate why a non-intuitive path was taken, as Invoice Sourour calls out, thereby saving future builders the hassle of the extra apparent (however incorrect) strategy.
Once more, the first emphasis must be to write down high-quality, concise code that (kind of) explains itself. The place this is not potential (and it isn’t at all times potential), “Consider feedback because the icing on the cake, that exist to offer the reader with data that may’t simply be expressed by the code itself,” to make use of Brian Hannaway’s phrases.
Importantly, he continues, it is vital to maintain your viewers in thoughts. It is a unhealthy assumption to assume that those that stumble upon your code later could have the identical stage of experience. As such, he has urged, cater to the much less skilled:
[Y]ou ought to make your feedback accessible and helpful to as broad a variety of readers as potential. In case you’re an skilled tech lead with robust area information, you should not remark in your code assuming that the [person] coming behind you’ll know as a lot as you do. As an alternative, write your feedback with much less skilled builders in thoughts.
In sum, there are nice causes to maintain feedback to a minimal, however they do not obviate the necessity for feedback altogether. You want subsequent builders to have the ability to perceive your code: That begins with writing clear, concise code, however ends with simply sufficient commentary to assist them perceive why you probably did issues a sure means.