338
What are your programming hot takes?
(lemmy.ml)
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 01 Sep 2023
338 points (96.2% liked)
Programming
17314 readers
179 users here now
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
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 1 year ago
MODERATORS
If your code files don't contain more lines of comments than lines of actual code, then you're doing it wrong. (For Python, docstrings count as comments)
And your comments shouldn't say what each line of code is doing. If you can code, then you can already tell what each line is doing by just reading the code. The comments should explain WHY it's being done this way, or HOW it's being done, or highlight some pitfalls that might snare a future developer, and generally just give some higher level context to a line or block of code.
@257m @programming
@TerrorBite @257m @programming
Comments are for revision control systems. We have a strictly no comments in code policy because comments too often end up being wrong or misleading throwing everyone believing in them for a wild ride. The only thing that is worse than bad code is bad comments.
When you read sensible and thorough commit messages you generally have the notion that whatever it says was probably true at the time of the commit, whereas when you read comments in code it can still be correct or just plain utterly wrong.
@nthcdr this assumes that people write sensible and thorough commit messages, instead of brief five-word ones or, say, song lyrics. Both of which I've seen.
I at least try, except maybe for the other day where my commit message consisted entirely of an exasperated "why", followed by a revert.
That being said, every commit message where I work is required to contain a ticket number (and the server will reject the push if you don't) so at least there's that for context.
@257m @programming
@TerrorBite
Yes there need to be some assumption that your co-workers write reasonable commit message even if they have their lapses now and then.
Another problem with comments in code is that they tend to be short because nobody likes to read code interspersed by walls of prose. But many times if something really needs explaining you also need a little more room doing it. Thus when committing in code people tend to gloss over important detail.
Then of course there is literate programming. The other end of the spectrum, but then we're talking code in documentation not comments in code.
@257m @programming