Hacker News new | past | comments | ask | show | jobs | submit login

> 8. You should always add lots of comments[0] to your code.

If I don't do this, when I come back to the code an hour later I have no idea what its supposed to do or why I wrote it. I'll also usually add an explanation, like "3 is bad number of args because..."

> 44. Funny names are funny, you can always change them later.

This one drives me crazy, I hate when people use something like "x" or "habberdasher" instead of something functional like "newspapers"

[0] https://twitter.com/jschauma/status/1044581775983276034




> If I don't do this, when I come back to the code an hour later I have no idea what its supposed to do or why I wrote it.

Many people write comments which are often nothing more than a really obvious transliteration of the code to English "foobar += 3; // Add 3 to the foobar".

These comments add little to nothing and often become worse than useless when they fall out of date and you end up with a cryptic "foobar += 7; // Add 3 to the foobar"

I find it helpful to imagine a codebase guru, someone who not only wrote the thing but has had years of experience maintaining and teaching to others... and the comment writes down what they would say if you asked them about it.

The guru wouldn't say 'adds three to foobar', they'd tell you about how the number used to be the obvious value of two but then the database choked when the boss was trying to store their golf scores in it, because foobar controls the whatzanits and there can be a race that requires it to have room for one extra. The guru would tell you _why_, and that's what a better comment will do.

Students of programming are often just writing what they're told to write. They don't necessarily have a strong grasp on the why, especially not a deep contextual grasp.


I once saw

    using namespace std; // using namespace standard


Worst comment I have seen was in an systems paper at Uni (assignments in a MIPS's like assembly language).

add $1, $2, $3 #add some stuff.


> If I don't do this, when I come back to the code an hour later I have no idea what its supposed to do or why I wrote it.

I think the point that the tweet is trying to make is that if you comment, you should explain why you are doing something instead of saying what you are doing. The latter is already written there, in code.


This is one of a few of my programming pet peeves. So many people I work with add comments which are completely just re-stating the code that follows. Ruby is particularly bad for this, at least visually.

  # authenticate user
  user.authenticate!


> If I don't do this, when I come back to the code an hour later

Good coding means two things, in general:

* There is no more understandable comment than no comment needed.

The code should explain _what_ it is doing as close as possible in words such that any programmer, including you, can read the code and understand what it is doing.

Bad: sum = a.length + b.length

Good: totalNumberOfGoodProducts = exceptionalProducts.length + acceptableProducts.length

* Comments should be the exception for _why_ something odd is happening.

Bad: if(r == 42) return; // Nothing happened.

Good: if(ioReturnCode == 42) return; // Ignoring code 42, an undocumented value and seems to be a "no operation happened." We'll retry again later in the code.


The better you get at writing code, the more the code documents itself, and the less comment writing you will need to do.

Think of writing a comment as a failure of your ability to write good code - we all fail from time to time but we asipre to do better over time.




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: