When it comes to code documentation, it is usually accepted that code should explain itself, and inline code documentation (excluding public API documentation) should only explain meta-code issues such as workarounds, explanations on why specific implementations were chosen, etc.
How do you accomplish making your code more readable and more explaining itself?
Edit: in addition to general comments, I'm also looking for specific tips. So if you say "short but meaningful variable names", it would be nice to also get a helpful tip as well (e.g. "use the three-word principle").
What enhances the readability of program?
In this article, we will look at four tips that can dramatically improve the readability of code and therefore hold the attention of the reader longer: (1) removing boilerplate code, (2) formatting indentation and spacing, (3) selecting appropriate names, and (4) removing unnecessary comments.
How does code readability enhance code maintainability?
Context: One of the factors that leads to improved code maintainability is its readability. When code is difficult to read, it is difficult for subsequent developers to understand its flow and its side effects. They are likely to introduce new bugs while trying to fix old bugs or adding new features.
What is readability of code in programming?
Readability in software programming can be defined by the ease with which the software is read and understood. Readability of software can be somewhat objective. Programmers who are “journeymen” and move from one project to another throughout their career tend to have an easier time reading a variety of software code.
Check out Jeff Atwood's Code Smells blog post. It pretty much sums it up. I'll add my personal ethos when it comes to good readable code:
- Consistency: this applies to formatting, using braces, naming (variables, classes, methods) and directory layout (if you bury a source directory somewhere under /css I'm coming after you with a machete);
- Size: if a function doesn't fit in its entirety on the screen in a normal IDE at a normal font size then you need a pretty darn good reason as to why not. Of course there are some valid cases for much longer functions but they are greatly outweighed by the egregious examples. Decompose as necessary to keep your functions simple;
- Comment Judiciously: there is a tendency for some programmers to use comments as a substitute for readable code or to simply comment for the sake of commenting (like
/* finished */ comments right before return true;. Seriously, what's the point? Most (good) code explains itself; - Never Cut and Paste Within a Project: it's perfectly acceptable to take a code snippet from one project to another (every project is an island) but you should never take a non-trivial code segment from within one project to some other point within the project. Inevitably one changes and you leave some poor developer with the task of looking at these two or more code segments trying to work out how (and arguably more importantly, why) they are different; and
- Avoid Repetitive Code: if you find yourself writing the same sequence of statements (or very similar) over and over again, abstract or parameterize it. If you see very similar statements the tendency is to skim over them assuming they're all the same (when typically they won't be in a way that matters).
Menu
215
