Legacy Code Documentation
-
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?
All documentation is out of date as soon as it's written. Code is never out of date.
-
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
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
-
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?
Is it really just the code, or a whole system? If a whole system, check and/or create a high-level overview, even if it "should be obvious" and make sure you have the documentation necessary to make a change, rebuild, test, distribute and install. (I.e. you have to go through that process to be sure it works). As for code, depends partly on how much expertise in the coding language(s) you think will be available if a change is necessary, particularly if people have used unusual language features or coded in an unusual way compared to "normal industry practice" - perhaps make a few general remarks noting such stuff.
-
Contrary to my last(vastly misunderstood post), this is not apparent, it simply is (for real). I am an OF and have noticed how "newer generations" choose NOT to use (simple) old, proven methods , stuff. My manager did not use AI or RTFM - his "comment or else " was based on "what will happen if you get run over by a bus and your code is not documented / commented?" For those hard of hearing - undocumented / uncommented code was against company interest, period. I am not a wiz kid, but if the code task is to test HARDWARE , CLOSE TO REAL TIME, and if the code is not documented , commented AND is missing ANY time reference - it will not "just " APPARENTLY fail - it will fail for sure. IMHO self documented code is oxymoron
What is an OF, and more to the point, what other post? Inquiring minds want to know (I looked at the thread, and this is your first post). But, I completely agree with your comment.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Is it really just the code, or a whole system? If a whole system, check and/or create a high-level overview, even if it "should be obvious" and make sure you have the documentation necessary to make a change, rebuild, test, distribute and install. (I.e. you have to go through that process to be sure it works). As for code, depends partly on how much expertise in the coding language(s) you think will be available if a change is necessary, particularly if people have used unusual language features or coded in an unusual way compared to "normal industry practice" - perhaps make a few general remarks noting such stuff.
THIS!!! Code does not exist on it's own. It was written to solve a problem. If you don't tie the code back to the problem, you lose context. Sometimes this is called tribal knowledge. I'm watching an organization bleed to death, but the multinational corp above it is oblivious. As my boss told me, it's not up to you to help a multi-billion dollar company fix their stupidity. 2 weeks later, I jumped out of the plane (with a parachute) and retired. It's been two months now, and I have not received a single email. :)
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
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
-
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:
// set x to 5
let x = 5;Well no duh. That is self-documenting and obvious, but stuff like this always isn't:
// keep the raw data for these, also bands should use the population
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
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
'NB loop starting at 1 is deliberate to skip headers
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)
-
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
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
-
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
-
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
'NB loop starting at 1 is deliberate to skip headers
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 :laugh: :laugh: :laugh:
Jeremy Falcon
-
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?
I just got a copy of some Fortran code I wrote in 1982. Thankfully, I put in a lot of comments. Sadly, I was missing one crucial comment, but I figured it out in about 10 hours. CQ de W5ALT
Walt Fair, Jr.PhD P. E. Comport Computing Specializing in Technical Engineering Software
-
What is an OF, and more to the point, what other post? Inquiring minds want to know (I looked at the thread, and this is your first post). But, I completely agree with your comment.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
OF = Old Fogey (or some ruder word that starts with F.)
-
I just got a copy of some Fortran code I wrote in 1982. Thankfully, I put in a lot of comments. Sadly, I was missing one crucial comment, but I figured it out in about 10 hours. CQ de W5ALT
Walt Fair, Jr.PhD P. E. Comport Computing Specializing in Technical Engineering Software
Old guru Tony Hoare remarked after reviewing the various proposals for Fortran-77 extensions (some of them went quite far, to phrase it in a polite manner): "I don't know what programming languages will look like in the year 2000, but I know that they will be named 'Fortran'." When I first saw code written to the Fortran-2003 standard, my immediate reaction was: Hoare was right! So my curious question is: How did your 1982 vintage Fortran code fare with a 2024 vintage Fortran compiler? (Fortran 77 was so much delayed that the '77' is a misnomer, so I wouldn't be surprised if 1982 vintage code is not even by the F77 standard.)
Religious freedom is the freedom to say that two plus two make five.
-
Old guru Tony Hoare remarked after reviewing the various proposals for Fortran-77 extensions (some of them went quite far, to phrase it in a polite manner): "I don't know what programming languages will look like in the year 2000, but I know that they will be named 'Fortran'." When I first saw code written to the Fortran-2003 standard, my immediate reaction was: Hoare was right! So my curious question is: How did your 1982 vintage Fortran code fare with a 2024 vintage Fortran compiler? (Fortran 77 was so much delayed that the '77' is a misnomer, so I wouldn't be surprised if 1982 vintage code is not even by the F77 standard.)
Religious freedom is the freedom to say that two plus two make five.
trønderen wrote: o my curious question is: How did your 1982 vintage Fortran code fare with a 2024 vintage Fortran compiler? I was translating the code to C#, so there was no problem, except I wonder if I had a brain 46 years ago. CQ de W5ALT
Walt Fair, Jr.PhD P. E. Comport Computing Specializing in Technical Engineering Software
-
OF = Old Fogey (or some ruder word that starts with F.)
-
Old guru Tony Hoare remarked after reviewing the various proposals for Fortran-77 extensions (some of them went quite far, to phrase it in a polite manner): "I don't know what programming languages will look like in the year 2000, but I know that they will be named 'Fortran'." When I first saw code written to the Fortran-2003 standard, my immediate reaction was: Hoare was right! So my curious question is: How did your 1982 vintage Fortran code fare with a 2024 vintage Fortran compiler? (Fortran 77 was so much delayed that the '77' is a misnomer, so I wouldn't be surprised if 1982 vintage code is not even by the F77 standard.)
Religious freedom is the freedom to say that two plus two make five.
Lord willing, I will be in this boat late this year or maybe next year. The FORTRAN production system I support breaks down into basic components: 1) UI. It's designed to allow order entry people to do it FAST. The new developers want to make the UI pretty, and they don't bother to talk to their customers. The customer is NOT The contract manager, it's the people in the factory. 2) Reports - enough said. 3) Number crunching to produce a manufacturing file. This is the grail. I cut my teeth on FORTRAN, but C and C++ allow string processing to a useful form. Trying to do it in FORTRAN brings tears to my eyes and my hemeroids swell.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
-
Lord willing, I will be in this boat late this year or maybe next year. The FORTRAN production system I support breaks down into basic components: 1) UI. It's designed to allow order entry people to do it FAST. The new developers want to make the UI pretty, and they don't bother to talk to their customers. The customer is NOT The contract manager, it's the people in the factory. 2) Reports - enough said. 3) Number crunching to produce a manufacturing file. This is the grail. I cut my teeth on FORTRAN, but C and C++ allow string processing to a useful form. Trying to do it in FORTRAN brings tears to my eyes and my hemeroids swell.
Charlie Gilley “They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759 Has never been more appropriate.
charlieg wrote: cut my teeth on FORTRAN, but C and C++ allow string processing to a useful form. Trying to do it in FORTRAN brings tears to my eyes and my hemeroids swell. been there, done that... It still hurts what brain I have left! CQ de W5ALT
Walt Fair, Jr.PhD P. E. Comport Computing Specializing in Technical Engineering Software