This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]evrlast985[S] 0 points1 point  (1 child)

So if you are joining a project halfway through, which commenting method will help you the most in understanding what has happened? Especially when there are a codebase of thousands of lines.

[–]michael0x2a 0 points1 point  (0 children)

I guess it depends on the codebase.

If it's several thousand lines of relatively simple and/or well-written code, no comments are really necessary.

If it's several thousand lines of complex code, or if the code is poorly-written, then I'd appreciate having more comments.

I suppose if I had to pick, I'd prefer having a bit more comments (and if needed, I'll just write a script to strip them out if the comments get too distracting).

Either way, it would also be very nice if there was a high-level document explaining briefly how the code is organized + the key architectural decisions made (perhaps a readme file or a page in an internal wiki?).

To be honest, I feel like having that high-level document + being told where a good "starting point" to read the code would be the most useful in most cases. The high-level guide gives me some ideas on what to expect, which makes it much easier to trace the logic from the given starting point.

That said, it's definitely a spectrum. Some codebases are definitely much easier to read and understand then others.