23
Literate Programming
(www.literateprogramming.com)
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Follow the wormhole through a path of communities !webdev@programming.dev
If a function has 300 lines without a lot of supporting documentation then I doubt that it is "clear, readable and concise" anyway.
I have never found it hard at all to skip past comments that are not relevant because my code editor helpfully colors them differently from the rest of the code, making it easy. Does your editor not do the same?
(Also, by now you should be especially good at skipping past it, given that you have apparently "read [it] hundreds of times" instead of skipping past it, for some reason.)
It depends on what you are doing. If you are implementing relatively simple logic like a REST API handler, then it is probably overkill. If you are implementing a relatively advanced algorithm, then having a running narrative of what is going can be extremely helpful.
Code - not function. Files often have multiple functions in them. If you can't read and understand code - I don't want you on my team.
If it's something people will simply skip over then it's not useful. Don't pollute code with tons of unnecessary comments that you think will be useful for some "perceived future". They just add to your maintenance work.
Write your code to be understandable and document the architecture/design separately.
Agree - most code is pretty straight forward. Save the comments for where it's needed.