|
Thanks for the intelligent reply, Daniel. Some peeps can't see outside the box they live in, ya know.
Jeremy Falcon
|
|
|
|
|
US Medical Industry.
GCS/GE d--(d) s-/+ a C+++ U+++ P-- L+@ E-- W+++ N+ o+ K- w+++ O? M-- V? PS+ PE Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
The shortest horror story: On Error Resume Next
|
|
|
|
|
Doctors, lawyers and consultants are all similar.
You pay regardless of if they fail or succeed.
|
|
|
|
|
Questions
Is it Maintained?
Do you look for it or just explore the code?
What do you do if it is not there?
Is the code documenting itself good enough?
|
|
|
|
|
(nervous laugh) Hahahahaha deep breath Hahahahaha!!!
When I'm going through undocumented legacy code, I write code comments worthy of a 1st year college student.
If there are function comments, I'll check them, add missing parameters comments and stuff like that.
We lost many, many years of expertise (retirements) in a short amount of time; so there is a lot of documentation going on.
CI/CD = Continuous Impediment/Continuous Despair
|
|
|
|
|
similar boat to you with retirements and a vast change in staff
|
|
|
|
|
Never trust documentation. There is no guarantee the last developer updated it when they changed the code. You can read it as a guide. So trust, but verify.
Hogan
|
|
|
|
|
ditto Snorkie Going on 40 yrs of reading, writing, editing code, both mine and others.
Could not agree more.
"A little time, a little trouble, your better day"
Badfinger
|
|
|
|
|
I hate that, and it's why I lean toward not commenting, and expressing intent through code, wherever I can.
Comments are a curse, even if they're sometimes necessary.
Check out my IoT graphics library here:
https://honeythecodewitch.com/gfx
And my IoT UI/User Experience library here:
https://honeythecodewitch.com/uix
|
|
|
|
|
There is a reasonable balance between documenting something and the overly detailed documentation that is likely to get out of date. I like the "here is a new thing and here is the general pattern of how it works" type of documentation. Code comments are reserved for "I know this is stupid, but users." And references to Kelly Clarkson to make the other devs laugh when they read my code. We have to have some fun around here.
Hogan
|
|
|
|
|
In code reviews, I tell the developers to remove all comments except ones that explain _why_ we needed to do something. The _what_ should be evident from reading the code. The worse comments are ones that only re-phrase the name of the class or method.
I deal with 30 year old code that is still being updated and maintained. You can tell lots of different programmers had their hands in the pot and not all of it is good code. For the first 20 years, no code reviews were done. I'm the last person on the team with more than 3 years experience (I have 24 years) on this codebase. If I leave, then they would be so lost in a lot of areas of the code. There is no way we could document all of it at this point.
Bond
Keep all things as simple as possible, but no simpler. -said someone, somewhere
|
|
|
|
|
This is my preference as well. Syntax can be googled, internal business process and reasoning cannot.
|
|
|
|
|
MarcusCole6833 wrote: Is it Maintained? Legacy code or not, if the code is updated the docs for it should be updated.
MarcusCole6833 wrote: Do you look for it or just explore the code? It should be a part of the code. jsdoc or doxygen style comments should be littered all throughout the code. There should also be READMEs in the project. No point in having to hunt down an external resource that would only get stale.
MarcusCole6833 wrote: What do you do if it is not there? Ask why it's not there with the original devs. If I'm now responsible for said legacy code and if there is some documentation somewhere then I'll try and add it to the project.
MarcusCole6833 wrote: Is the code documenting itself good enough? No. This goes back to the age old "what makes a good comment" issue. People that say code is always self-documenting are just wrong. They've never worked with other humans and certainly was never a professional dev.
What makes a good comment? Not stuff like this:
let x = 5;
Well no duh. That is self-documenting and obvious, but stuff like this always isn't:
const average = [...simpleMovingAverage(sample, range)].pop()?.actual ?? 0 as Price;
const band = standardDeviation(sample.map((x: Market) => x.close), true).actual * deviations;
Not everyone maintaining the code may know off the top of their head the note about how something should be implemented. One could argue RTFM, but let's be realistic... people maintaining code do not Google every last line of code. Also, there may be no well-known manual for some things.
It's easy for someone to "fix" it and break it and even get past a PR. So, when you do something that may be considered unusual or haphazard or just only known by a select few having a comment should present to make it explicit. As such, I don't consider code always self-documenting in the real world.
Jeremy Falcon
|
|
|
|
|
Jeremy Falcon wrote: Ask why it's not there with the original devs. If I'm now responsible for said legacy code and if there is some documentation somewhere then I'll try and add it to the project.
The original devs are all retired
(lol, not joking).
CI/CD = Continuous Impediment/Continuous Despair
|
|
|
|
|
Quote: People that say code is always self-documenting are just wrong. They've never worked with other humans and certainly was never a professional dev. Thank you, thank you, thank you!
I've lost count of the number of arguments I've had about this. I've also lost count of the number times I've gone into my own code after some time and silently thanked Earlier Me for comments like
//Outputs have to match previous provider, so yes, converting this number to text here is correct and
I used to often include links to Sharepoint documents in comments. Stopped doing that after a company "rationalised" their document storage (euphemism for moved to different provider and did not migrate all documents)
|
|
|
|
|
CHill60 wrote: I've gone into my own code after some time and silently thanked Earlier Me for comments like Same
Jeremy Falcon
|
|
|
|
|
These are strange times, we got some young developers who were told by their teacher at the local school that documentation was not necessary, said teacher seems to be a follower of the "code should be self documenting" doctrine.
|
|
|
|
|
Maybe have them analyze a complicated method from your code base, after the comments are removed.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
Well, to be fair, some of our code is so complicated that even with documentation no one can understand it anymore
|
|
|
|
|
Maybe one of the rookies is a savant and could explain it to you, then you could document it better?
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
Younger programmers, yes I know them and have experience with them.
Yes, they can program very nice websites for you. They also know all the new features of e.g. c#.
But it seems that they have no ability to get to grips with a specific business, let alone understand its basics in the very minimal basics.
[Edit]
Would you trust a surgeon who simply knows how to cut open a body part, do something on what's inside it and sew it back up...
... or would you not prefer more, it if the surgeon also had specific knowledge of how to operate on a heart, a hip joint or a knee, etc.?
modified 31-Jul-24 15:22pm.
|
|
|
|
|
MarcusCole6833 wrote: Is the code documenting itself good enough?
I am personally a big fan of using descriptive variables such that the code becomes self-explanatory. I also have a standard set of names for common-use objects that could incriminate identify me as the author.
Edit: That said, when the intent is not clear, or you/they are doing something 'clever', then documenting/commenting is encouraged.
Comments may or may not get updated, but the code doesn't lie.
"Go forth into the source" - Neal Morse
"Hope is contagious"
|
|
|
|
|
I think calling it "self-explanatory" is a bit of a stretch. Although consistent naming is a big plus and something I strive for, it's also important to document why it was done the way it was unless it's obvious. Along the lines of your final point, I've referred to code as the urtext.
|
|
|
|
|
kmoorevs wrote: you/they are doing something 'clever', then documenting/commenting is encouraged. I maintain as a strong rule: 'Clever' code should be avoided, if at all possible. If it can be rewritten in a more readable way, do so -- even if timing of that specific loop shows that it takes 40% more time. Most likely is is 0.01% of the total run time for the application.
Comments may or may not get updated, but the code doesn't lie. Well ... The comment may still be the honest truth of what the code was intended to do. The code may be honest about the coder's misconceptions, or possibly his intent to impress with his 'smartness', without succeeding
Religious freedom is the freedom to say that two plus two make five.
|
|
|
|
|
kmoorevs wrote: Comments may or may not get updated, but the code doesn't lie. Unless that code is being refactored and the naming butchered by some other dev. While I do agree good naming is important, it doesn't remove the need for comments completely. Blanket statements is typically the tell tale sign of the inexperienced.
Jeremy Falcon
|
|
|
|