The Art and Science of Great Code • Hacker News Board

Re: The Art and Science of Great Code

#31

Post by pnathan » Fri, Nov 04, 2011, 2:57 PM UTC

nahname wrote: post #27

kellishaver wrote: post #9

Earlier quoted context omitted.

This is interesting, and not something I'd consciously thought about before, but quite often I will go back after I've finished something and add some white space and (sometimes quite thorough) comments to the code I've written. I especially do this with open source code that I plan to release. My reason for doing this is that I want to make it clear to whoever ends up maintaining the code after I've left the project…

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…

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

Re: The Art and Science of Great Code

#32

Post by kellishaver » Fri, Nov 04, 2011, 7:43 PM UTC

nahname wrote: post #27

kellishaver wrote: post #9

Earlier quoted context omitted.

This is interesting, and not something I'd consciously thought about before, but quite often I will go back after I've finished something and add some white space and (sometimes quite thorough) comments to the code I've written. I especially do this with open source code that I plan to release. My reason for doing this is that I want to make it clear to whoever ends up maintaining the code after I've left the project…

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…

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

Re: The Art and Science of Great Code

#33

Post by nahname » Sat, Nov 05, 2011, 6:22 AM UTC

kellishaver wrote: post #32

nahname wrote: post #27

Earlier quoted context omitted.

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…

Thanks 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…

I am glad the comment (heh) helped you in some way.

Re: The Art and Science of Great Code

#34

Post by marchdown » Sun, Nov 06, 2011, 5:52 PM UTC

jacques_chester wrote: post #12

Is it just me, or does this read like pages randomly plucked from Code Complete ? Not that that's a bad thing. But I'd expect better from the ACM.

What's wrong with Code Complete? You might pick a couple of nits, but these things have to be explained somewhere, and Steve McConnell does a good job there.

Re: The Art and Science of Great Code

#35

Post by jacques_chester » Fri, Nov 11, 2011, 1:43 AM UTC

marchdown wrote: post #34

jacques_chester wrote: post #12

Is it just me, or does this read like pages randomly plucked from Code Complete ? Not that that's a bad thing. But I'd expect better from the ACM.

What's wrong with Code Complete ? You might pick a couple of nits, but these things have to be explained somewhere, and Steve McConnell does a good job there.

I was criticism the article, not Code Complete. I love that book, I still have my first edition.