6

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

nobrandheroes
  • 748
  • 1
  • 10
  • 17

9 Answers9

5

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).

Justin Niessner
  • 242,243
  • 40
  • 408
  • 536
  • Hmm, too much of a good thing is a bad thing for sure. No reason for superfluous, pseudocode comments. That being said, I do think you should use comments for code that isn't going to be obvious to other programmers (or to you 6 months later). – clifgriffin Sep 28 '10 at 13:02
  • 1
    @clifgriffin - I can be convinced. But keep in mind though...even your example follows my suggestion. If I were using good naming conventions and designing my classes correctly, my if statement to check for a valid user would be `if(currentUser.IsValid)` which is self explanatory. – Justin Niessner Sep 28 '10 at 13:04
  • Comments should be there to tell other people your intent. That way they can compare what you think the code does with what it actually does and if the two differ, it's a sign of a bug. – JeremyP Sep 28 '10 at 13:12
  • @JeremyP - A well named method should show intent. Well written code should be readable enough that somebody looking at the code should be able to tell what is happening and where the issue is. – Justin Niessner Sep 28 '10 at 13:14
  • 1
    @Justin Niessner: I'm sorry but that is crap. If, say, a private sort method sorts the specified sub-array of longs into ascending order, then your are NOT going to call that method *sortSubArrayOfLongIntoAscendingOrder* or you have a **VERY** serious issue of Java-illness. You name your method *sort* or *sortSubarray* AND you add a one line comment explaining what that private sort method does. This an example from the JDK and it is a Good Thing [TM]. The problem with "self-explanatory method names" is that you need a 320 columns-wide screen ;) Not exactly my definition of readable code. – SyntaxT3rr0r Sep 28 '10 at 13:52
  • @Justin Niessner: oh, and the most beautiful code I have here (from an Adobe programmer who worked on the Photoshop codebase) was beautiful from every standpoint, including beautiful comments. And, no, I can't share it ;) – SyntaxT3rr0r Sep 28 '10 at 13:53
  • @Webinator - `sortSubArray` is a fine name. Remember that writing comments in code and documenting what a method does for documentation purposes are two completely different things (although using XML comments and auto-generating documentation blurs the line...but I still think that leans toward the documentation side). – Justin Niessner Sep 28 '10 at 13:54
  • 1
    @Justin Niessner: Speaking from experience of maintaining other people's code, believe me, you are wrong. It's all very well to say "well written code blah blah blah" but I live in the real World. – JeremyP Sep 28 '10 at 16:26
  • @Justin Niessner: Also, if you think you can describe a function's API in just a few characters, you are in dreamland. If you have a Unix system to hand type `man strcat` and then tell me what function name you would use to encapsulate all the information – JeremyP Sep 28 '10 at 16:27
  • 1
    @JeremyP - First of all, this question is about human readable code not real world code. I've maintained other people's code for quite some time and I can tell you that self-documenting code is the easiest code I've ever had to read/maintain. And I've already mentioned that documentation is not equal to in-code comments (as far as man strcat is concerned). – Justin Niessner Sep 28 '10 at 17:03
5

Proper indention and informative comments.

Ruel
  • 15,438
  • 7
  • 38
  • 49
5

  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.

clifgriffin
  • 2,008
  • 3
  • 21
  • 41
5

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

Ilian Iliev
  • 3,217
  • 4
  • 26
  • 51
3

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

matt b
  • 138,234
  • 66
  • 282
  • 345
3

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

Andreas Dolk
  • 113,398
  • 19
  • 180
  • 268
2

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.

Yuval
  • 7,987
  • 12
  • 40
  • 54
  • 3
    While I agree with your approach, I think the Impl naming convention is an awful one. If StringToDateTransformer is an interface, the implementation class should be named after the Method that's used, e.g. JodaTimeStringToDateTransformer. Just like List vs ArrayList / LinkedList – Sean Patrick Floyd Sep 28 '10 at 12:52
  • Naming conventions are subjective, so to each his own. The point here is to avoid shorthand out of laziness, because long names make the code more readable. – Yuval Sep 28 '10 at 17:25
  • And BTW, `org.apache.commons.collections15.Transformer` is a generic interface worth knowing... very useful! – Yuval Sep 28 '10 at 17:31
2

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.

Raveline
  • 2,660
  • 1
  • 24
  • 28
1

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!

Jeff Meyers
  • 144
  • 5