Programming

3 readers

1 users here now

This magazine is dedicated to discussions on programming languages, software development, and coding. Whether you are a beginner programmer or an experienced developer, this is the place for you. Here you can share your knowledge, ask questions, and engage in discussions on topics such as coding languages, software engineering, web development, and more. From the latest trends and frameworks to tips and tricks for debugging, this category covers a wide range of topics related to programming.

founded 2 years ago

Code comments are (mostly) a violation of DRY (danielrotter.at)

submitted 1 year ago by danrot@kbin.social to c/programming@kbin.social

17 comments fedilink hide all child comments

Comments in code are quite often a code smell. Let’s see what is suboptimal about comments and talk about some strategies to avoid them.

you are viewing a single comment's thread
view the rest of the comments

[–] pirate526@kbin.social 5 points 1 year ago (2 children)

While I agree with some of the premises here, I personally disagree that comments are even mostly a problem (a code smell). IMO they’re just as often bad as code is. A developer in a rush, or simply not taking enough care in their work, can produce both bad code and bad comments.

Perhaps someone who is trying to take care can do more harm in the comments area, when they should be perhaps looking at writing self documenting code, but in my experience they usually go hand in hand.

I use quite a lot of comments in my code and I wouldn’t regard it as code smell or even messy. I often use comments to logically separate more complex sections of functionality.. or discussing how it works and why it’s necessary to exist in the first place. Code can’t always tell you why it’s there..

I also use docblocks in some libraries, even though types are available, as the published package benefits from having an API document published alongside it. The comments there facilitate its construction.

I know this article wasn’t bashing every use of comments in code but I feel like it didn’t account for all the positive uses of them either. Teaching developers that a language feature is just mostly bad is irresponsible - we should be encouraging good comment use alongside clear code.

[–] burliman@lemm.ee 1 points 1 year ago

The code is the “what”, the comments are the “why”. It’s the mantra I use when making them. So in a fundamental way, they never repeat themselves.

[–] danrot@kbin.social 1 points 1 year ago

I agree with almost all of what you say, but the thing IME is that in most cases people learn to comment a lot, which results in comments that feel like they've been done just for the sake of it, which is one of the main problems IMO. It's not like "just add a comment, it won't hurt", since comments can be immensely misleading and literally take a lot of time until figuring out that the comment was wrong if you trust the wrong ones.

I also agree that this tends to be worse with bad code, which also is not surprising. Sometimes it feels to me like people think they can fix bad code with some comments, and I think that is far from being true.

I also admit that especially the title of the article might be a bit provocative, but giving the general positive sentiment of comments I think this is called for. Sometimes you have to exaggerate a bit to get some attention. I don't like click-baiting either, but unfortunately it works ;-)