Discussion on: What makes for readable code?

[Ryan Smith]

My tips:

• Consistent formatting.
  • Helps in scanning files if everything is "as it should be", exact styles aren't as significant as some make them out to be, but consistency is.
• Naming things well.
  • Some developers have trouble with this, but I like to think of it in a simplistic way. If someone came to you and asked "what does this do?", rephrase the response into a name. If every variable is a basic noun, things can get muddled and there is extra overhead to understand the code when repeat names that are basic continue to show up. Being slightly more descriptive makes a huge difference.
• Comments that are complete sentences (subject/predicate) that do not only restate the code.
  • I don't say that to test English, but I have seen a lot of comments that are very vague or cryptic. They might be a sentence fragment or phrased as a question without a question mark, so it can be confusing as to what the meaning is.
• Avoiding brevity and making code for humans to read.
  • Abbreviations and acronyms might make sense when writing it, but it might not mean anything to others or yourself in the future.