- Simulation6 ( @Simulation6@sopuli.xyz ) 56•20 hours ago
Figuring out what the code is doing is not the hard part. Documenting the reason you want it to do that (domain knowledge) is the hard part.
- tatterdemalion ( @tatterdemalion@programming.dev ) 14•20 hours ago
Agreed.
And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what’s happening, in SVG format, embedded into the function documentation HTML.
- hex ( @hex@programming.dev ) 3•8 hours ago
Yeah. I advocate for self explanatory code, but I definitely don’t frown upon comments. Comments are super useful but soooo overused. I have coworkers that aren’t that great that would definitely comment on the most basic if statements. That’s why we have to push self explanatory code, because some beginners think they need to say:
//prints to the console console.log("hello world");
I think by my logic, comments are kind of an advanced level concept, lol. Like you shouldn’t really start using comments often until you’re writing some pretty complex code, or using a giant codebase.
- TehPers ( @TehPers@beehaw.org ) English2•4 hours ago
Sometimes when I don’t leave comments like that, I get review comments asking what the line does. Code like
ThisMethodInitsTheService()
with comments like “what does this do?” in the review.So now I comment a lot. Apparently reading code is hard for some people, even code that tells you exactly what it does in very simple terms.
- hex ( @hex@programming.dev ) 2•4 hours ago
Fair. I guess in this case, it’s a manner of gauging who you’re working with. I’d much rather answer a question once in a while than over-comment (since refactors often make comments worthless and they’re so easy to miss…), but if it’s a regular occurrence, yeah it would get on my nerves. Read the fuckin name of the function! Or better yet go check out what the function does!
- Flamekebab ( @Flamekebab@piefed.social ) 4•15 hours ago
TempleOS: Hold my communion wine
- lobut ( @lobut@lemmy.ca ) 1•18 hours ago
I can’t recall the exact change but a coworker did something five years very intentionally. The comments, the commit and everything described what they did but not why.
I think it was with side effects: true and I fixed a certain way we bundled things and I believe that could have solved the issue but I don’t know for sure :/
- koper ( @koper@feddit.nl ) 14•20 hours ago
Why the
password.trim()
? Silently removing parts of the password can lead to dangerous bugs and tells me the developer didn’t peoperly consider how to sanitize input.I remember once my password for a particular organization had a space at the end. I could log in to all LDAP-connected applications, except for one that would insist my password was wrong. A
trim()
or similar was likely the culprit.- spechter ( @spechter@lemmy.ml ) 12•20 hours ago
Another favorite of mine is truncating the password to a certain length w/o informing the user.
- NotationalSymmetry ( @NotationalSymmetry@ani.social ) English6•16 hours ago
Saving the password truncates but validation doesn’t. So it just fails every time you try to log in with no explanation. The number of times I have seen this in a production website is too damn high.
- Flipper ( @Flipper@feddit.org ) 3•18 hours ago
The password needs to be 8 letters long and may only contain the alphabet. Also we don’t tell you this requirement or tell you that setting the password went wrong. We just lock you out.
- HamsterRage ( @HamsterRage@lemmy.ca ) 6•17 hours ago
The reason for leaving in the
password.trim()
would be one of the few things that I would ever document with a comment. Thanks for the tip. password.trim() can indeed be problematic. I just removed that line.
- Rogue ( @Rogue@feddit.uk ) 3•15 hours ago
A quick glance and this seemed nothing to do with self documenting code and everything to do with the flaws when code isn’t strictly typed.