5 ms·

The #1 most important factor in coding is: Will I be able to read my code tomorrow or next week and know what in the heck I did?

timr 14y ago
Which really means: did I spend the time to write good comments? People will go to endless lengths to make their code more terse and/or "self-documenting", but almost nobody takes the five extra minutes it takes to write an intelligent comment. The comments are far more important.
- randomdata 14y ago
  I have to wonder what a good comment gives that a good set of tests wouldn't also provide, plus all of the extra benefits that come from having automated tests? It seems like they both exist to solve the same problem (to explain intent, show usage, etc.), with just one being more formal about it.
  - jfim 14y ago
    Sometimes, code is hard to read due to being optimized. In that case, it's often easier to read a short comment than having to parse the code. // p.xyz += f.xyz * timeStep __m128 ts = _mm_load1_ps(&timeStep); __m128 x, y, z; __m128 fx, fy, fz; for(int i = 0; i < NUM_PARTICLES; i+=4) { x = _mm_load_ps(px + i); y = _mm_load_ps(py + i); z = _mm_load_ps(pz + i); fx = _mm_load_ps(pfx + i); fy = _mm_load_ps(pfy + i); fz = _mm_load_ps(pfz + i); x = _mm_add_ps(_mm_mul_ps(fx, ts), x); y = _mm_add_ps(_mm_mul_ps(fy, ts), y); z = _mm_add_ps(_mm_mul_ps(fz, ts), z); _mm_store_ps(px + i, x); _mm_store_ps(py + i, y); _mm_store_ps(pz + i, z); } Sometimes, it's because you're doing something that looks surprising, but is there for some reason, so that the next time someone looks at that code, they know why something is done in that fashion. val loginForm = Form( tuple( "email" -> text, "password" -> text, "rememberMe" -> optional(text) // jfim: HACK For some reason, having this as boolean causes a None.get in Play 2.1.0 ) ) Comments should be there to explain why the code does something or what it does in a more readable fashion(because it's faster to read plain English than code), neither of which can be covered by tests.
    - randomdata 14y ago
      I actually agree with you completely, but such cases should be rare, and doesn't seem to be what the parent was talking about.
- tonyedgecombe 14y ago
  That's fine if you have a team disciplined enough to write useful comments and keep them up to date. Personally I haven't seen that very often.
- jamesaguilar 14y ago
  I don't really agree. Which is to say, good comments are helpful, but they are a flashlight in a dark room. If there's lots of furniture and clutter in the room, you still might trip over something. How many times in your codebase have you seen a comment like: // This exists because that dumb thing happened, // and during the migration from Y to Z we had to // support these two systems simultaneously. This // component mediates between the two . . . And someone had added some common logic into the mediator, then someone else had hooked into that, and now there's a snarl. The most important thing is that the system be as simple as it can while still performing its intended functions. We have all made a first cut at something that ended up being three times as verbose or complicated as our second. You want a system made out of pieces of the second kind. That's even more important than comments. I can definitely understand the desire to reduce lines of code, because it's often a good proxy for understanding how complicated a system is. Not always, but most of the time, something a quarter as long that does the same job is doing it a simpler way.
  - timr 14y ago
    That's an easy question: it almost never happens. The most frequent occurrence (by far) is that there are no comments at all, just a wall of indecipherable code. Even an old comment describing intent and usage is better than no comments at all. In your example, even if that comment is outdated, it's still incredibly useful. It tells you, in under 5 seconds, the original intent of a piece of code, and how it was supposed to fit into the entire system. That's something you'll never get without a comprehensive understanding of the project, which takes far more than 5 seconds of reading. The real problem here is not that there is a comment -- the problem is that a bad coder fucked up by not updating the comment. There's no excuse. That all of the commenters below will spend paragraphs explaining how they shouldn't have to document their code with the occasional descriptive comment is an amazing testament to the overwhelming power of human laziness and self-delusion.
    - jamesaguilar 14y ago
      My point is not that this comment is unhelpful. My point is that it would be better if the reason for this comment's existence were eliminated. I.e. that the removal of unnecessary complication in the system is an even more laudable goal than commenting well. Obviously, both will have a part in any well written an maintained system. But the person I'm responding to held good comments up as the most important aspect of system maintainability, and that is simply not the case.
- JamesLeonis 14y ago
  I try to avoid having to write implementation comments. If I find I need comments, then it's a warning that I may be too clever by half. I prefer a description of what the function is supposed to do rather than how it accomplishes it's goal. Even so, there are some times when I need to write some mentally dense code to accomplish several competing goals. It is then where I explain what's going on and why the code was built that way.
- saraid216 14y ago
  Just to add to siblings, I'd propose a rule of thumb of at most 2 sentences per "page" of code, where a page is about as much code is on your screen at a readable size. It's a rule of thumb, and snark will put you over that easily, but IME, it can suggest you're getting overzealous about commenting when you've got more than that.

timr 14y ago

Which really means: did I spend the time to write good comments? People will go to endless lengths to make their code more terse and/or "self-documenting", but almost nobody takes the five extra minutes it takes to write an intelligent comment. The comments are far more important.

randomdata 14y ago
I have to wonder what a good comment gives that a good set of tests wouldn't also provide, plus all of the extra benefits that come from having automated tests? It seems like they both exist to solve the same problem (to explain intent, show usage, etc.), with just one being more formal about it.
- jfim 14y ago
  Sometimes, code is hard to read due to being optimized. In that case, it's often easier to read a short comment than having to parse the code. // p.xyz += f.xyz * timeStep __m128 ts = _mm_load1_ps(&timeStep); __m128 x, y, z; __m128 fx, fy, fz; for(int i = 0; i < NUM_PARTICLES; i+=4) { x = _mm_load_ps(px + i); y = _mm_load_ps(py + i); z = _mm_load_ps(pz + i); fx = _mm_load_ps(pfx + i); fy = _mm_load_ps(pfy + i); fz = _mm_load_ps(pfz + i); x = _mm_add_ps(_mm_mul_ps(fx, ts), x); y = _mm_add_ps(_mm_mul_ps(fy, ts), y); z = _mm_add_ps(_mm_mul_ps(fz, ts), z); _mm_store_ps(px + i, x); _mm_store_ps(py + i, y); _mm_store_ps(pz + i, z); } Sometimes, it's because you're doing something that looks surprising, but is there for some reason, so that the next time someone looks at that code, they know why something is done in that fashion. val loginForm = Form( tuple( "email" -> text, "password" -> text, "rememberMe" -> optional(text) // jfim: HACK For some reason, having this as boolean causes a None.get in Play 2.1.0 ) ) Comments should be there to explain why the code does something or what it does in a more readable fashion(because it's faster to read plain English than code), neither of which can be covered by tests.
  - randomdata 14y ago
    I actually agree with you completely, but such cases should be rare, and doesn't seem to be what the parent was talking about.
tonyedgecombe 14y ago
That's fine if you have a team disciplined enough to write useful comments and keep them up to date. Personally I haven't seen that very often.
jamesaguilar 14y ago
I don't really agree. Which is to say, good comments are helpful, but they are a flashlight in a dark room. If there's lots of furniture and clutter in the room, you still might trip over something. How many times in your codebase have you seen a comment like: // This exists because that dumb thing happened, // and during the migration from Y to Z we had to // support these two systems simultaneously. This // component mediates between the two . . . And someone had added some common logic into the mediator, then someone else had hooked into that, and now there's a snarl. The most important thing is that the system be as simple as it can while still performing its intended functions. We have all made a first cut at something that ended up being three times as verbose or complicated as our second. You want a system made out of pieces of the second kind. That's even more important than comments. I can definitely understand the desire to reduce lines of code, because it's often a good proxy for understanding how complicated a system is. Not always, but most of the time, something a quarter as long that does the same job is doing it a simpler way.
- timr 14y ago
  That's an easy question: it almost never happens. The most frequent occurrence (by far) is that there are no comments at all, just a wall of indecipherable code. Even an old comment describing intent and usage is better than no comments at all. In your example, even if that comment is outdated, it's still incredibly useful. It tells you, in under 5 seconds, the original intent of a piece of code, and how it was supposed to fit into the entire system. That's something you'll never get without a comprehensive understanding of the project, which takes far more than 5 seconds of reading. The real problem here is not that there is a comment -- the problem is that a bad coder fucked up by not updating the comment. There's no excuse. That all of the commenters below will spend paragraphs explaining how they shouldn't have to document their code with the occasional descriptive comment is an amazing testament to the overwhelming power of human laziness and self-delusion.
  - jamesaguilar 14y ago
    My point is not that this comment is unhelpful. My point is that it would be better if the reason for this comment's existence were eliminated. I.e. that the removal of unnecessary complication in the system is an even more laudable goal than commenting well. Obviously, both will have a part in any well written an maintained system. But the person I'm responding to held good comments up as the most important aspect of system maintainability, and that is simply not the case.
JamesLeonis 14y ago
I try to avoid having to write implementation comments. If I find I need comments, then it's a warning that I may be too clever by half. I prefer a description of what the function is supposed to do rather than how it accomplishes it's goal. Even so, there are some times when I need to write some mentally dense code to accomplish several competing goals. It is then where I explain what's going on and why the code was built that way.
saraid216 14y ago
Just to add to siblings, I'd propose a rule of thumb of at most 2 sentences per "page" of code, where a page is about as much code is on your screen at a readable size. It's a rule of thumb, and snark will put you over that easily, but IME, it can suggest you're getting overzealous about commenting when you've got more than that.