4 ms·

My impression...as you become more experienced, your comments will tend more towards confession and pleas for forgiveness... //XXX I don't know why this work

My impression...as you become more experienced, your comments will tend more towards confession and pleas for forgiveness... //XXX I don't know why this works ... //XXX Worst kludge of my life ... //FIXME this whole pile of crap needs re-written

spydez 18y ago
My favorite comment that I've personally written: // Here there be magic. See datasheet for details; they explain it // almost as well as I just did. (followed by ~10 lines of math chock full of magic numbers.)
- jgrahamc 18y ago
  I maintained a piece of 250,000 line C code that had one comment in it (apart from copyright notices): /* bad code */ To this day I do not know if this was a comment on the quality of the code that came after it, or if the developer was reprimanding the code.
gruseom 18y ago
Comments like this seem cowardly to me. If you can do better, then do. If you can't, write the best code you can and be enough of a man or woman to commit what you did and not clutter it up with excuses.
- cconstantine 18y ago
  In a perfect world those kinds of comments would never be written. Unfortunately there are times when there simply isn't time to do it the Right Way (tm). In those times when you have to do it the Fast and Ugly (tm) way, it's nice to make a comment that you really don't like the code. It adds some humor, and lets the maintainer know that there is no emotional attachment to that section of code.
  - gruseom 18y ago
    there simply isn't time to do it the Right Way Of course, this is the first thing that everybody says. And since everybody says it, everybody thinks it must be true. But my experience has been that if you really want to do good work, it turns out not to be true (say) 80% of the time. So the next time you find yourself making a mess because you believe you "have to", you could try stopping and questioning that assumption. You might surprise yourself. How do you think I learned this? Certainly not by following what the majority of programmers believe. Edit: Rather than using phrases like "the Right Way", I'd suggest toning things down and looking for a way. There are many ways. If you get in the habit of thinking there's only one, and it's capitalized and trademarked, the bar seems a lot higher than it really is.
    - cconstantine 18y ago
      In the dev team I'm on we are constantly working within "aggressive" deadlines. Almost daily we come across a problem, brainstorm the ways of fixing it, and choose a path. Most of the time we can pick the one everyone agrees is the best way, or the Right Way. Every once in awhile we're stuck at 3 days to code freeze (the product isn't a website, so we physically send out a DVD with our product on it, so quietly pushing out hotfixes isn't an option) and come across a bug that almost no user will care about that has two solutions: 1) Fix the problem the correct way. We don't know exactly what the correct way is, but we know it'll take a month or longer to code. 2) Apply some hack that gets it to work. This is usually something ugly and imperfect, but it's possible to do in 2 hours. We can tackle the problem again and attempt to get at a better solution. If we don't ship on time, we lose piles of money. Guess which one we end up choosing ;) Option 2 is fairly rarely chosen, but all it takes is for it to happen once or twice to have comments like the above in code, and forgotten. Right... that whole Right Way (tm) thing is mostly tongue in cheek. It almost always refers to the way I want it done, and is a fairly flexible way.
    - DanHulton 18y ago
      Clearly you have never worked in a situation with a looming deadline. Sometimes there is simply no time to clean things up, you just have to extend from whatever code you have, no matter how ugly, because you aren't given the go-ahead to spend the extra time cleaning.
- icey 18y ago
  You don't have to know the right answer to know if the answer you've chosen isn't the optimal one. While I'm sure it'd be nice to know all of the answers all the time, some of us mere mortals can continue to try to notify other people that extra attention should be paid to the code following those comments.
- Hexstream 18y ago
  I'm a perfectionist, and sometimes the only way I can make progress in my project is to do it the hacky way while documenting the promise to return later to fix it into a comment in the style of: "Lazy shortcut." Sometimes doing it The Right Way would necessitate a big refactoring of the supporting code or learning a concept in more depth and I can't afford all that overhead (which might break flow also). Also, sometimes a far-reaching refactoring might be carried out in stages over a number of hours or days and to go from where you are to The Right Thing you'll have to pass through a number of less-than-optimal stages. But I always find it easier and faster to use an incremental approach where I accept suboptimal solutions, most of which will be quickly overwritten anyway than trying to do The Right Thing all at once.
- marijn 18y ago
  Nonsense. Often your code will be ugly because some API in other code is broken or missing (see a lot of JavaScript), or doing something the right way is too slow or complicated, and you don't happen to have enough time to make a research project out of it. So then you add a self-deprecating comment to provide a little joy in the existence of the poor schmuck who will have to maintain your mess. Everybody wins. Kinda.
DanielBMarkham 18y ago
One of the most insightful things I've read here all week. Sometimes I think I should make a macro out of //HACK:

spydez 18y ago

My favorite comment that I've personally written: // Here there be magic. See datasheet for details; they explain it // almost as well as I just did. (followed by ~10 lines of math chock full of magic numbers.)

jgrahamc 18y ago
I maintained a piece of 250,000 line C code that had one comment in it (apart from copyright notices): /* bad code */ To this day I do not know if this was a comment on the quality of the code that came after it, or if the developer was reprimanding the code.

gruseom 18y ago

Comments like this seem cowardly to me. If you can do better, then do. If you can't, write the best code you can and be enough of a man or woman to commit what you did and not clutter it up with excuses.

cconstantine 18y ago
In a perfect world those kinds of comments would never be written. Unfortunately there are times when there simply isn't time to do it the Right Way (tm). In those times when you have to do it the Fast and Ugly (tm) way, it's nice to make a comment that you really don't like the code. It adds some humor, and lets the maintainer know that there is no emotional attachment to that section of code.
- gruseom 18y ago
  there simply isn't time to do it the Right Way Of course, this is the first thing that everybody says. And since everybody says it, everybody thinks it must be true. But my experience has been that if you really want to do good work, it turns out not to be true (say) 80% of the time. So the next time you find yourself making a mess because you believe you "have to", you could try stopping and questioning that assumption. You might surprise yourself. How do you think I learned this? Certainly not by following what the majority of programmers believe. Edit: Rather than using phrases like "the Right Way", I'd suggest toning things down and looking for a way. There are many ways. If you get in the habit of thinking there's only one, and it's capitalized and trademarked, the bar seems a lot higher than it really is.
  - cconstantine 18y ago
    In the dev team I'm on we are constantly working within "aggressive" deadlines. Almost daily we come across a problem, brainstorm the ways of fixing it, and choose a path. Most of the time we can pick the one everyone agrees is the best way, or the Right Way. Every once in awhile we're stuck at 3 days to code freeze (the product isn't a website, so we physically send out a DVD with our product on it, so quietly pushing out hotfixes isn't an option) and come across a bug that almost no user will care about that has two solutions: 1) Fix the problem the correct way. We don't know exactly what the correct way is, but we know it'll take a month or longer to code. 2) Apply some hack that gets it to work. This is usually something ugly and imperfect, but it's possible to do in 2 hours. We can tackle the problem again and attempt to get at a better solution. If we don't ship on time, we lose piles of money. Guess which one we end up choosing ;) Option 2 is fairly rarely chosen, but all it takes is for it to happen once or twice to have comments like the above in code, and forgotten. Right... that whole Right Way (tm) thing is mostly tongue in cheek. It almost always refers to the way I want it done, and is a fairly flexible way.
  - DanHulton 18y ago
    Clearly you have never worked in a situation with a looming deadline. Sometimes there is simply no time to clean things up, you just have to extend from whatever code you have, no matter how ugly, because you aren't given the go-ahead to spend the extra time cleaning.
icey 18y ago
You don't have to know the right answer to know if the answer you've chosen isn't the optimal one. While I'm sure it'd be nice to know all of the answers all the time, some of us mere mortals can continue to try to notify other people that extra attention should be paid to the code following those comments.
Hexstream 18y ago
I'm a perfectionist, and sometimes the only way I can make progress in my project is to do it the hacky way while documenting the promise to return later to fix it into a comment in the style of: "Lazy shortcut." Sometimes doing it The Right Way would necessitate a big refactoring of the supporting code or learning a concept in more depth and I can't afford all that overhead (which might break flow also). Also, sometimes a far-reaching refactoring might be carried out in stages over a number of hours or days and to go from where you are to The Right Thing you'll have to pass through a number of less-than-optimal stages. But I always find it easier and faster to use an incremental approach where I accept suboptimal solutions, most of which will be quickly overwritten anyway than trying to do The Right Thing all at once.
marijn 18y ago
Nonsense. Often your code will be ugly because some API in other code is broken or missing (see a lot of JavaScript), or doing something the right way is too slow or complicated, and you don't happen to have enough time to make a research project out of it. So then you add a self-deprecating comment to provide a little joy in the existence of the poor schmuck who will have to maintain your mess. Everybody wins. Kinda.

DanielBMarkham 18y ago

One of the most insightful things I've read here all week. Sometimes I think I should make a macro out of //HACK: