21–30 of 60 posts
I don't mind using code folding when I'm doing this. Trying to fold the code down that I don't care about, this way there isn't as much to read and get lost in.
If you're not folding functions, but parts of functions, that's a sign that it's poorly divided up, and a refactor would benefit it.
Let's not con ourselves. Becoming a dab hand at maintaining other people's software does not make you a good software developer (writing your own software does that). It makes you a good employee who is willing to do the boring shit. The two are not the same. I for one hate maintaining other people's code, and if I ended up doing that the majority of the time, I would either get a new job, switch careers or kill myself. Probably one of the first two.
I don't know about the rest of you but I got into software development to create software (ideally from scratch) and to learn clever new stuff, not to tinker with someone else's code. Of course, just like every other software developer, I have on occasions ended up working in someone else's codebase. But I have done this not out of choice - and except in a handful of cases, I have not gained any knowledge or mental s…
The idea is that reading good code makes you a better coder. Which it certainly does. Having said that, bad code can sometimes teach you lessons in how not to do things.
Good authors probably read other books as well.
Earlier quoted context omitted.
When I was studying CS, one of the things I was told was that if you grep and get only the comments out of a particular file/class, you should effectively see the pseudo-code of the program. In reality, I comment very little, just pointing things out that can’t be quickly deduced from casually reading the code.
I hope you don't still believe that's a good idea! That's a recipe for out-of-date documentation. Even if the comments are up-to-date they'll only be saying things that can be inferred from the code itself, less precisely.
But even though refactoring is supposed to be perfectly mechanical and "harmless" (especially when supported with unit tests) I'll usually throw away my refactoring, because the risk of breaking the existing code is just too high. It depends on how invasive the new feature is -- if I'm going to have to change a lot to get it done anyway, I might as well incorporate the refactorings. But if the change literally is finding the right position to add a single line of code, no way I'm going to change things once I find it.
When it's clear that adding even simple features takes an extraordinary amount of time because the code is that hard to understand and maintain, getting/making time for proper refactoring is easier, but it's worthwhile even as a way of creating a mental model.
I've never tried unit tests to figure out the semantics of existing code, though, even if it seems obvious in retrospect. I think the code base would have to become very complicated indeed before I go into full scientist mode and construct hypotheses on the semantics and verify them with unit tests. If the code is a tangled mess, it could also be tough to extract the proper bits to test on and/or set up a test environment complete enough for that.
One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Reading the code makes also for reviewing the code. Quickly changing bits so it makes better sense (like counts outside the for-loop instead of in the statement) etc. And use version-control system to make changes, test them and roll it back (revert). TortoiseSVN h…
I'm also at least slightly troubled by the assertion (not made Aschwin, but others) that the code is the only artifact worth reviewing. If you have a specification, or documentation, that doesn't line up with the product, why do you have those documents in the first place? Again, I don't expect that those documents will outline the specific implementation (though, if your shop uses software design documents, they should), but I should be able to get a reasonable explanation of how the system works from the docs. If this isn't the case, how do you expect to have someone test the system?
All that said, I agree that having the ability to read and understand others' code is critical to being a good programmer.
One of the reasons I don't write comments is because it gets outdated so quickly. And I don't need them myself, because I read only the code, even my own. Reading the code makes also for reviewing the code. Quickly changing bits so it makes better sense (like counts outside the for-loop instead of in the statement) etc. And use version-control system to make changes, test them and roll it back (revert). TortoiseSVN h…
Now that you know how comments can fail, you should use that knowledge to write good comments rather than not writing any. There are plenty of very good reasons to write comments. The most common reason I write comments is to explain the purpose of something that is unintuitive from the pure code. Examples are comments in CSS about a particular browser quirk, or hacking around an edge case in an efficient but opaque…
One of the first things I'll do encountering a feral code base is run an automatic documentation generator over it, even if there are no API comments, because many will produce at least some level of documentation from pure code, including cross references, a type index, call graphs, type diagrams, etc. This can be especially helpful when the code is poorly organized, and trying to trace simple program flow in an editor means navigating a dozen modules manually. Doxygen, for instance, will produce hyperlinked program listing, so that I can use a browser in a natural fashion to navigate the code structure and program flow. The browser can maintain virtually unlimited context, whereas my brain loses track of where I am once I'm seven levels deep in function call nesting.
Some IDEs and UML tools also are capable of reverse engineering documentation from the code base. The Togethersoft tools used to be excellent at grinding through code (and may still be, but I haven't used them in years).
RE'ed documentation of feral code can reveal how well (or more frequently poorly) the code base is structured, and identify key areas for architectural or design refactoring (if that luxury is possible).
In writing my own code, I decompose until each function or method has a single purpose (f() does X, not X & Y & Z!), and therefore the API documentation suffices to document the code itself. Rarely do I write a comment inside the body of a function or method. That happens when I re-visit the code, and discover that it's operation is non-obvious. The non-obvious stuff tends to be the tricky stuff it took some time to get right, and so it doesn't get mucked around with, and such internal comments rarely go stale.
I wait until re-visiting the code because authorial bias (my code effectively become's someone else's after several weeks, sometimes faster :-) ) obscures what is and is not obvious. I used to over-comment from a tendency to perform a mini-brain dump in comments -- but the knowledge required to WRITE the code (this is what I was thinking at the moment) is no reliable indicator of that required to READ the code (this is what _you_ need to know).
(I've theorized that having someone else comment the code from the start, just like having an unbiased tester, could make for better comments -- wherein the commenter is also necessarily a code reviewer as well. I've never gotten any of the places I've worked to agree to 'cross-commenting' as a standard practise, but most love worthless, perfunctory desk-checks prior to check in.)
To avoid comment churn, and because I refactor aggressively when creating brand new code, writing API comments is the LAST step in coding.
Finally, I developed a habit of writing comments exclusively in point form, because context switching from programming constructs to proper English grammar broke my flow. The point form comments feel like a miniature brain dump, whereas otherwise I'd pause to think about how to put the information into a proper sentence, and then make nice paragraphs, and suddenly I'd be channeling me from 7th grade compsition class. It's also easier to scan and digest comments as point form notes.
That's what I do, and I leave it at that, because telling someone else how to code is like telling them how to raise their children.
tl;dr version
- at least write API comments, pls
- doc generators (and other tools) sometimes are a great way to RE docs for feral code
- write comments in point form
- write API comments as the FINAL step in coding
- try to remove authorial bias from comment writing
One productive technique to read other people's code is to step into the code using a debugger (e.g. gdb)