As mentioned in my other comment, names will rarely explain the reasons why a given solution was chosen. These reasons are important from maintenance perspective and should be recorded next to the relevant code.
A software engineer that loves Disroot and the team behind it.
As mentioned in my other comment, names will rarely explain the reasons why a given solution was chosen. These reasons are important from maintenance perspective and should be recorded next to the relevant code.
You’re definitely not the only one.
In my opinion the important information we should record in comments is WHY, because the code can only explain HOW, maybe WHEN, but never WHY. If we don’t know WHY, any refactoring done in the future could break the logic by ignoring assumptions made by the authors.
I’m beginning to feel we’re no longer talking about Clean Code being bad, but about people following ideas they don’t understand, which is not related or caused to any particular book.
I hope your book won’t have a table of context and those stupid indexes. If they read it, they should know where you mention topics, right? Tables of contents considered harmful! /s
I’d love to learn what that damage was. I often see complaints (sometimes also involving tech choices) but usually they’re not specific, so I’m always left wondering.
I’m not going to argue, because I don’t know your work environment, but the notes I mentioned weren’t supposed to be published or attached to the product. They’re more of a personal knowledge base, where you can look up former approaches, issues found in the past, reasoning, decisions with context… All the zettelkasten tools out there do exactly that: help maintaining a useful knowledge base.
That’s the next level of trolling!
That’s why we keep notes… Literate DevOps is a solution for my preferred editor, but there definitely are solutions for other tools too, even if they don’t work exactly the same.
I can’t recommend keeping notes too much.
I want people like you around me!
I often skip meetings without agenda. If they don’t care to prepare a reasonable invitation, I don’t care to join. Also - I skip meetings where they announce stuff. Announcements should go to my inbox, so I can read them when ready, not when they think it’s suitable for them.
I definitely agree that too many comments is often a bad sign, esp. when large part of them is obviously generated.