26 Communicate in Code

Practices of an Agile Developer — by Venkat Subramaniam, Andy Hunt (31 / 58)

👈 25 Program Intently and Expressively | TOC | 27 Actively Evaluate Trade-Offs 👉

Programmers generally hate writing documentation. That’s because most documentation is kept separate from the code and becomes hard to keep up-to-date. Besides violating the DRY principle (Don’t Repeat Yourself, in The Pragmatic Programmer: From Journeyman to Master [HT00]), it can lead to misleading documentation, which is generally worse than none at all.

You need to document your code in two ways: using the code itself and using comments to communicate noncode issues.

If you have to read through a method in order to understand what it does, you wind up investing a lot of time and effort before you can use that method in your own code. On the other hand, a few lines of comments that describe the behavior of the method can make your life easier. You quickly learn its intent, what its expectations are, and what you need to watch out for — saving you a lot of effort.

Should you document all your code? To some extent, yes. But that doesn’t mean you need comments for most of the code you write, especially within the body of your methods. Source code should be understandable not because it has comments but because of its elegance and clarity — proper use of variable names, good use of whitespace, good separation of logic, and concise expression.

Naming is a big deal. The names of program elements are often all the reader of the code has to go on.[27] By using well-chosen names, you can convey a lot of intent and information to the reader. On the other hand, using artificial naming schemes (such as the now-rebarbative Hungarian Notation) can make the code harder to read and understand. These schemes bombard you with low-level…

Related posts:

I cannot get enough of fantasy romance novels lately. I don’t know what it is about mythological wars and magical powers that make me fall in love with the characters, but lately fantasy romance has…

Every single time I sweep my floors, I think, “Didn’t I just do this?” Every single time there is a pile of dirt, crumbs, and dust that needs to be swept away. And, every single time it always amazes…