32 ms·
I've spent quite a bit of time working on systems that became untenable and had to be partially re-written or completely re-written. The result is the original
by nahname 15y ago
I've spent quite a bit of time working on systems that became untenable and had to be partially re-written or completely re-written. The result is the original code was either a baseline or a reference. I will say, without a doubt, comments are a code smell. Any comments.
If you write a piece of code and think you need to comment it because it won't be clear for the next guy. It is good at best.
Furthermore, comments rarely help. They are written while you are in complete comprehension of the program or that part of it. The next person (assuming the comment is something they are using to figure it out) won't be.
That said, if you can do nothing to improve the quality because of time, lack of interest or necessary complexity. At least, make your best effort to comment what it does. Appreciating the fact that this is a minimal quality improvement action. Sometimes it is just a piece of code that has to be optimized, explain why so the next guy doesn't refactor/re-write it.
- pnathan 15y agoI have done research programming into new algorithms in a pretty exotic area. Those sorts of algorithms are not comprehensible without documentation, ie, comments. OTOH, outside of that, I would agree that comments have a limited use.
- kellishaver 15y agoThanks very much for the perspective. Personally, I think (and judging from the reactions of the people I work with, they seem to agree) that my code is solid; efficient, well organized, logical, descriptive, but not too verbose, etc. Your comment has made me go back and re-evaluate some things, though, and look over some of those comments - and it was at that point that I realized that a lot of them are superfluous and serve no real purpose other than to restate what's already clear in the code. Others in the particular code I was looking at were about things like UI customization and how one might extend the existing code in order to do that, which more correctly belongs in the documentation (and would have wound up there eventually). Again, most of this had been in open source PHP/Ruby/JavaScript code, where I'd assumed that the average tinkerer wouldn't be as well-versed in the language, but now that I think about it, if they're not, they need to learn before tinkering, rather than me trying to "dumb it down" to their level, which probably just invites disaster on multiple fronts. So in my attempts to make things tidy and easy for the next person to come along, I was instead just injecting garbage that didn't need to be there. Which kind of sucks to realize, but on the other hand, I suppose it's better than realizing you've been commenting the hell out of everything because the code actually doesn't make sense without the comments.
- nahname 15y agoI am glad the comment (heh) helped you in some way.