Yes, you don't need to comment "n++" to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, "This function has to return -2 as a default because we've been calling it using X for years and it expects a -1 as the error…"
this function returns -2 as success and -1 as error
Thats exactly the kind of thing I'm talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don't own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you've tried everything else, should be
I've worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.
okay. doesn't mean you still shouldn't refactor or add a layer of abstraction where you can. we're looking for a generalizable principle here and generalizable principles don't assume that you're working with satellites that are older than the dev.
Yes, you don't need to comment "n++" to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, "This function has to return -2 as a default because we've been calling it using X for years and it expects a -1 as the error…"
Thats exactly the kind of thing I'm talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don't own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you've tried everything else, should be
return -1; //-1 indicates successI've worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.
okay. doesn't mean you still shouldn't refactor or add a layer of abstraction where you can. we're looking for a generalizable principle here and generalizable principles don't assume that you're working with satellites that are older than the dev.