Programming

The code already describes what it does, your comments should describe why it does that, so the purpose of the code.

Your code should generally be self documenting: Have variable and method names that make sense.

Use comments when you need to explain something that might not be obvious to someone reading the code.

Also have documentation for your APIs: The interfaces between your components.

Good comments describe the "why" or rationale. Not the what. This function doesn't need any comments at all... but it needs a far better name like logAndReturnSeed. That said, depending on what specifically you're doing I'd probably advocate for not printing the value in this function because it feels weird so I'd probably end up writing this function like

def function rollD10() -> int:
    return random.randInt(1, 10)

And I, as a senior developer, think that level of comments is great.

You mentioned that this is a trivial example but the main skill in commenting is using it sparingly when it adds value - so a more realistic example might be more helpful.

The big problem in your code is that the function name isn't descriptive. If I'm 500 lines down seeing this function called, how do I know what you're trying to do? I'm going to have to scroll up 500 lines to find out. The function name should be descriptive.

I find too verbose comments less annoying than no comments.

Try to describe the bigger picture. Good comments allow understanding the current portion of the code without reading other code.

Also add comments later if you find yourself having to read other code to understand the code you're currently looking at.

Comments are also a good place to write out abrevations/acronyms.

Never optimize for sourcecode size.

I expected this comment section to be a mess, but actually it's really good:

• "why not what"
• "as self-documenting as possible"

If you want an example, look at the Atom codebase. It is incredibly well done.

I like to do two kinds of comments:

• Summarize and explain larger parts of code at the top of classes and methods. What is their purpose, how do they tackle the problem, how should they be used, and so on.
• Add labels/subtitles to smaller chunks of code (maybe 4-10 lines) so people can quickly navigate them without having to read line by line. Stuff like "Loading data from X", "Converting from X to Y", "Handling case X". Occasionally I'll slip in a "because ..." to explain unusual or unexpected circumstances, e.g. an API doesn't follow expected standards or its own documentation. Chunks requiring more explanation than that should probably be extracted into separate methods.

There is no need to explain what every line of code is doing, coders can read the code itself for that. Instead focus on what part of the overall task a certain chunk of code is handling, and on things that might actually need explaining.

I rarely read comments in code, that is from within source code anyway. I of course write comments explaining the behavior of public facing interfaces and otherwise where they serve to generate documentation, but very rarely otherwise. And I use that generated documentation. So in a roundabout way I do read comments but outside of the code base.

For instance I might use godoc to get a general idea of components but if I’m in the code I’ll be reading the code instead.

As others have said, your code generally but not always should clearly express what it does. It is fine to comment why you have decided to implement something in a way that isn’t immediately clear.

I’m not saying others don’t read comments in code; some do. I just never find myself looking at docs in code. The most important skill I have cultivated over the decades has been learning to read and follow the actual code itself.

Write comments for functions

"Function x creates a number and prints it to the console"

"Function x fetches new content from the fediverse"

Commenting print("hello world") with "print hello world" doesn't make too much sense

There are several types of documentation:

1. Line or block comments. Reserved for when you're doing something non-obvious, like a hack, a workaround because of a bug that can't be fixed yet etc. Designed to help other programmers (or yourself a few months later) to understand what's going on. Ideally you shouldn't have any of these but life ain't perfect.
2. If parts of your code are intended to be used as libraries, modules, APIs etc. there are standard methods of documenting those and extracting the documentation automatically in a readable format — like JavaDoc, Swagger etc. Modern IDEs will generate interface hints on the fly so most people nowadays rely on those, but they're not a 100% substitute for the human-written description next to a class or method.
3. Unit tests describe the intent for a piece of code and offer concrete pass/fail instructions. Same goes for other type of tests, like end to end tests, regression tests etc. All tests come with specific frameworks, which have their own methods of outlining specifications.
4. Speaking of specifications those are also a very important type of documentation. Usually provided by the product owner and fleshed out by technical people like architects or team leads, they're documented in tools like JIRA as part of the development process. They are at the core of the work done by programmers and testers.
5. Speaking of processes and procedures, it helps everybody if they're documented as well, usually in a wiki. They help a new hire get up to speed faster and they explain how the toolchains are set up for development, testing, deployment and bug fixing.
6. The human interfaces are a particularly interesting and important aspect and they're usually modeled and shared in specific tools by UX people.
7. Last but not least the technical as well as business designs should be documented as well. These usually circulate as PDF, DOC, Excel, PPT over email and file shares. Typically made and contributed to by business analysts and software architects.

For new code I'm writing I'm using mostly JsDoc function headers on public methods of classes and exported functions. With one or two sentences explaining what function does.

Also try to explain what to expect in edge cases, like when you pass am empty string, null, ... stuff of that nature - for which I then create unit tests.

I also always mention if a function is pure or not or if a method changes the state of its object. On a sidenote I find it odd that almost no language has a keyword for pure functions or readonly methods.

If I add a big new chunk of code that spans multiple files but is somewhat closed off, I create a md file explaining the big picture. For example I recently added my own closed off library to my angular frontend that handles websocket stuff like subscribing, unsubscribing, buffering, pausing,... for which a created a md file explaining it.