Are there any basic standards and practices for making human readable code?

Question

More specifically making HTML, Java, and python more readable? Does anyone have suggestions for this programming student?

Answer 1

1. Use consistent casing and naming.

2. Use tabs (and brackets where available) to provide a visual flow.

3. Use comments that explain what's happening conceptually as well as technically. (e.g., //Do we have a valid user? not //Check that user_ID is not -1)

I'm sure some more seasoned developers will have more suggestions, but those are my top 3.

Answer 2

Proper indention and informative comments.

Answer 3

Use indentation, comments and coding conventions( for Python check PEP8 )

Answer 4

Make sure your code is well structured (proper indentation, blank lines to separate sections of code, etc.) and use standard, consistent, and fully named (rather than incomprehensible abbreviated) variable names.

Others would suggest using proper comments. I would tend to disagree. If your code is well structured and variables well named, then comments would just clutter things up. The exception to the rule being when you must do something counter-intuitive to work around a bug somewhere else (I've had to resort to this in WCF and Entity Framework code in the past).

Answer 5

Try to read your code out loud (or at least in your head).

Answer 6

Have a look at this book: Clean Code: a handbook of agile software craftsmanship. It is all about making code readable and understandable.

Answer 7

One piece of advice is not to be lazy with names. For example, if you have a Java class which is an implementation of the Transformer interface, and it transforms String to Date, don't hesitate to name the class StringToDateTransformerImpl.

Answer 8

Well, you can always use the "ignorant test". Show your code to someone who knows absolutely nothing about programmation. If he can see more or less what a function does, the code is probably readable.

Answer 9

Proper indentation when writing HTML can be a lifesaver, especially when you're interacting with any sort of nested elements. Just be consistent with the indentation and be sure to update surrounding lines when you move or delete an indented element. This makes it much easier to update the page, as the level of indentation will give a clue as to where you are in the page without resorting to some sort of Ctrl+F maneuver.

It's also worth noting that if you're using CSS in conjunction with HTML, proper naming is critical! It will improve your workflow and the readability of your code.

I'm also a big fan of indentation, spacing, and comments when writing "real" (Java, Python, C, etc.) code. I lean towards (x + 1) over (x+1) because I personally think it makes a big difference in readability. I space out casts, increments, etc. and they catch my eye much more easily. Be consistent with your bracket/indentation style, and comment liberally - remember, re-writing a method name is not a comment!