Search code examples
commentsagilescrumlegacy-code

Adding comments to code in legacy apps/code at company in industry?

I am a junior software engineer at a company in the USA. And as many as you engineers know, many times I run into heavily undocumented code, with little to no/zero comments (I mostly code in Java).

Now, I know you might say the logical response of "well, comment the code then dude!", which I have done before, but something I have noticed is that the entire codebase is uncommented, so it looks "weird" having a few commented methods and such out of the blue. It would probably take many more hours or sometimes I simply lack the information on the "grand" scale of how the application or system operates, so I would not be able to comment the entire codebase or functionality.

I wanted to ask you fellow software engineers who also have uncommented/undocumented legacy applications and work in industry if:

  1. I should be fixing and commenting the entire codebase when I work on defects/bugs and new features
  2. Leave it alone since its a legacy application and follow the pattern that was set before (no comments)
  3. Comment individual pieces as I work on the application over time
  4. Are simple comments like // this is a comment preferred or java-doc style comments? (below):
     /**
     * 
     * @param the four byte rgb pixel value from image
     * @return the bitwise AND of the rgb value and a bitmask
     */

Thank you!

Solution

  • The fact is, there is no "right" answer to this question. The first question I would ask is: does your company or team have agreed upon development practices? If so, commenting practices should at least have a passing mention in there. There are some people who believe well-written code is self-explanatory and needs no comments. This could be the case there. It could also be the case that they believe that but their code is not self-explanatory - that would be a different conversation. Not having an agreement in the team or department will make anything you try to do a losing battle.

    To your specific questions:

    1. No. If you have a whole code base that is not documented or commented and you take that on without direction or approval, you are committing an astronomical amount of time and money to something that no one asked for. At the least you will make people upset with you. At worst, I've seen people fired for this kind of thing.

    2. This is probably an equally unhelpful extreme. It doesn't have to be all or nothing and this doesn't improve the code base or really contribute anything positive and you'll probably just frustrate yourself.

    3. This probably makes the most sense, but I stress again, talk to your team about agreed practices. Maybe suggest in a retro (since you have a scrum tag) that there is time put into each backlog item to do this for affected code. I bet you aren't the only person who thinks this way.

    4. Some teams like one, some teams like another. Talk to people, but in the end, it probably doesn't matter. The main difference I've seen in all my years of programming is poorly done inline comments can get lost and with poorly done block comments, you can lose pieces of code. Doing either badly makes it harder to follow. Doing either well makes it easier.