Wednesday, September 26, 2007

Code Is Prose

Coding is a form of expression. We can draw many parallels between coding and writing; we write code, we are the authors of the code. When we code, we are actually translating our ideas and understandings into the the programming language. By that line of reasoning, a program is a user manual (or essay or poem, take your pick) that we write in a programming language.

Code is for reading
(and execution too)
The computer doesn't care how we write the code as long as it works - no indentation is fine, cryptic lines are fine. We should try to get as close to natural language as possible. Do not go overboard though! Code like checkWhetherTheQueueIsEmpty() are no-no's though! Advise, but do not condescend.

Code is read many more times than it is written; code is WORM (Write Once Read Many). Debugging will be done on the code that you write more times than you write actual functionality into it. The code-maintainer will curse you less (he will curse anyway!) if the code you wrote, even if it is wrong, is easily understood. So code with meaning and gain some good karma!

But the clincher argument would be that we would have less of those pesky comments to write!

"Programs must be written for people to read, and only incidentally for machines to execute."
- Abelson & Sussman, SICP

* Avoid meaningless names.

* The meaning should not be ambiguous.

* Do not ever use a name that will not occur naturally to a person debugging the code.

* Do not abbreviate unnecessarily. Even if the abbreviation is logical to you, it might not be to another person.

* Vowel-swallowing is not desirable, nt_dsrbl at all.

* Be consistent. If you use underscores in your names to separate words, please don't use camel-case elsewhere and vice versa.
a) Capitalization -
b) Abbreviations - If you have to abbreviate (more often than not, this is a case of "I like to, hence I will") , then at least abbreviate consistently.

Recommended reading
Literate programming
Writing Unmaintainable code (original)
Writing Unmaintainable code(expanded)