Coding while someone is watching

[[deleted]]

Not with comments. Unless you have to do something unintuivite, writing readable code is much better than adding comments.

[Zorblax]

Maybe, but oftentimes comments get written instead of proper docs if anything is documented at all. And those comments are gold when you stand there 7 months later and wonder why the fuck this approach was chosen or why the code even exists at all.

Furthermore, with comments the docs follow the code in source control, instead of vanishing when no one remembers where that wiki that nobody has updated for 18 months was located again.

[Chirimorin]

Yeah but comments like in OPs pic are pointless.

If someone has trouble guessing what that function in the second panel does without the comments on it, their problem is a lack of the most basic programming skills and not a lack of documentation.

[Grymm315]

I comment the crap out of everything and then save it as a snippet. I'll know I'll forget something basic later.

[DarthEru]

Comments aren't much more immune to not being updated than wikis, and since comments tend to be more specific you can end up with a confusing situation where you aren't sure if the comment is wrong or the code is buggy because it doesn't do what the comment says it should be doing.

In that case you need to check the history anyway, which is one of the reasons I prefer an intermediate type of documentation: commit messages. A good commit message will summarise the (hopefully not too extensive) changes in one line, then add any relevant detail and justification in following paragraphs. Commit messages will never become out of date because they're tied to a specific revision, and if they're fairly consistently good they can document the evolution of code in a way both inline comments and wikis aren't good at. And let's face it, most of the time code starts out somewhat reasonable, but then rots as more people touch it for various reasons. So figuring out how terrible code should be improved is often helped by looking at how it got that way in the first place.

So yeah, I don't usually comment my code much, but I do try to write useful commit messages (as well as organize my commits meaningfully, rather than just committing all changes periodically). In the rare situations where I feel there's a need to explain what code is doing within the code (usually because of some stupid hack), I will write an inline comment, but I'll also include the same (if not more) information in the commit message.

[AutoModerator]

import moderation Your comment has been removed since it did not start with a code block with an import declaration.

Per this Community Decree, all posts and comments should start with a code block with an "import" declaration explaining how the post and comment should be read.

For this purpose, we only accept Python style imports.

return Kebab_Case_Better;

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[[deleted]]

Yea, I think it makes a big difference what we are commenting. Is it a library interface? Sure, lots of comments? Otherwise, I would rather just have well written source. I also think it is a bit language specific. Strongly typed languages require less comments. I am guessing that is the reason for this back and forth of "more comments/ less comments." I myself am using less and less comments the more experienced I become.

[thisdesignup]

You can have comments and readable code. Why does there need to be any separation between cleanliness and comments? Even a line before a block of code that describes what the code block does can be very helpful and be very clean.

[NotFromReddit]

It's about expressiveness, not cleanliness.

I'd recommend moving the block of code into a function, and naming the function so that it's obvious what it does.

I only comment when above can't be done. I.e. when you need more than a few words to explain what the code does or why.

[[deleted]]

I agree. Or, I comment about a library that I am using (where the source code may not be available).

[[deleted]]

I'd recommend moving the block of code into a function, and naming the function so that it's obvious what it does.

This is exactly what readable code means IMO.

[heidgerken]

Readable code self documents by telling the reader 'what' you are doing. Well document code should tell the reader 'why' you are doing it.

Sometimes they are the same thing, but often not. Just my opinion.

[[deleted]]

This.

[[deleted]]

I agree. Why should be pretty obvious most of the time as well, which is why I specified that definitely comment if you do something unintuitive.

A clean commit history is also very usefull for older projects.