3

I started a new job a couple months ago. I came onto a project with tens of thousands of lines of C code.

The codebase is huge and there is little to no useful documentation. When I need information about the code, I need to consult one of two other engineers.

This usually results in me having to bother one of them every 15 minutes. It's about to get worse since one of them is leaving this week.

It's extremely difficult for me to focus at this job and I'm afraid I'll lose it. I find it difficult to go to the office and stay focused.

Is this my fault? What can I do to make this job work? I've found in past jobs that my best work has been when I was able to design and write the codebase from scratch myself, which, no surprise, is much easier than coming onto a new project and being expected to be useful right away.

Old_Lamplighter
  • 159,693
  • 108
  • 436
  • 585
Silas Mollod
  • 103
  • 3
  • 1
    Have you spoken to your boss and asked about the possibility of creating some documentation? – JasonJ Jul 26 '16 at 18:07
  • I don't feel comfortable being "that guy" that complains about the documentation. I've been on such projects before. I know why there isn't much... deadlines. Perhaps I just have bad communication skills. I just want this job to work. I want to not loathe coming in every day. – Silas Mollod Jul 26 '16 at 18:28
  • @SilasMollod how comfortable will you be being "that guy" who's out on the streets because he didn't ask questions? – Old_Lamplighter Jul 26 '16 at 19:08
  • 1
    Coming to terms with a legacy codebase is an art form in itself. There's an excellent interview with Dave Thomas of pragmatic programmer fame about this ( http://www.se-radio.net/2009/11/episode-148-software-archaeology-with-dave-thomas/). It's just a skill you need to exercise. Have you tried doxygen? – teego1967 Jul 26 '16 at 23:17
  • 1
    Possible duplicate of Poor documentation culture – Jim G. Jul 27 '16 at 01:00
  • 2
    Step 1: Learn to use your tools. Step 2: Add documentation saying what which code does. Step 3: When you run into code that you don't understand ask. Either there's something subtle that should have been documented, or it's a bug. Find out which and either add a comment or fix the bug. – gnasher729 Jul 27 '16 at 14:33

4 Answers4

8

Your situation is very normal. Programmers always want to write code from scratch rather than decipher what was written before, but the world doesn't often work that way.

It might be a good idea to sit down with the existing engineers and get a "broad overview" of what the software does, where to start when researching a particular bug or feature, etc. Do not expect volumes of up to date documentation -- if it doesn't exist today, it's not going to exist.

You need to focus more on learning the skills to answer your questions yourself by examining the code.

In short, step up your diagnostic and debugging skills and work hard to become a senior programmer. As you gain confidence and experience your stress and other issues will decrease significantly.

Eventually the new people will be coming to you for answers.

Dan Pichelman
  • 31,511
  • 16
  • 93
  • 103
  • I think you downplay just how difficult it is to get anything done when modifying the code is so difficult. Perhaps it's not just the lack of documentation, but also the fact that the code is just hard to work with. The build system is esoteric. For some reason I need to rebuild the entire thing from scratch every time I edit a header file. That's just one example. So perhaps it's not just the lack of documentation. – Silas Mollod Jul 26 '16 at 18:18
  • @JoeStrazzere If it weren't "C" code, I'd agree with you. "C" code is hard to maintain to begin with – Old_Lamplighter Jul 26 '16 at 18:50
  • You should bold " In short, step up your diagnostic and debugging skills " – HLGEM Jul 26 '16 at 18:50
  • 4
    All legacy code is hard to work with. The stuff you wrote from scratch will be hard to work with in five-ten years too. – HLGEM Jul 26 '16 at 18:51
  • 3
    The only way this gets fixed is if *you* start documenting the code as you work through it. Meanwhile, yes, the other engineers are your documentation; use them judiciously but as necessary. – keshlam Jul 26 '16 at 18:59
  • @HLGEM Not true. Well documented code with meaningful variable names is easy to maintain 20 years down the line. – Old_Lamplighter Jul 26 '16 at 19:05
  • @SilasMollod so its more than poor documentation - have you talked to anyone about why the build system is esoteric? what if you came along with a solution that fixed this - wouldn't that make you the hero? – HorusKol Jul 26 '16 at 23:53
  • @JoeStrazzere not normal for battle hardened coders like us, and I'm dealing with an undocumented kluge right now. But I can see how it would drive a younger person up a wall, especially today when troubleshooting and maintenance coding isn't taught anymore. – Old_Lamplighter Jul 27 '16 at 10:58
  • 1
    Was troubleshooting and maintenance ever taught? – gnasher729 Jul 27 '16 at 14:35
5

You say you don't want to be "that guy" that complains about documentation.

The simple solution is to not complain - and get on documenting.

As you start to figure out the nooks and crannies of the legacy code, document it. Then start suggesting improvements.

You say the build system is esoteric - find out why, and come up with a plan to improve it.

You're right that you don't want to be "that guy" who complains - why not become "that guy" who made things better?

(If you don't get any support for improving things - start looking for another job)

HorusKol
  • 27,459
  • 11
  • 65
  • 102
1

Maintaining code is a far different from being a developer.

As a maintenance coder, you have to be half psychologist because you need to figure out the developer's thinking. You are lucky enough to have the developers as coworkers. Don't feel bad about bothering them. That said, learn from this example.

As John Woods wrote:

"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability."

The best thing you can do at this position is to learn from the developers, learn how they do things and add your own documentation as you go along. When they explain the code, don't just take notes, go back into the source and add comments and documentation.

This is a good practice in general, as the day will come when you're maintaining your own code and will be happy that you took the time to document.

Old_Lamplighter
  • 159,693
  • 108
  • 436
  • 585
0

"Koff, koff ..." I suppose that, having dealt with this same situation for well over thirty-five(!) years, I've grown quite used to it.

To me, it's clear that you are confronting "legacy code" for the first time.   And so, if you are accustomed to "I was able to design and write the codebase from scratch myself ..." ... uh huh, "it comes as a wee bit of a shock."

I surmise that your immediate concern is: "being expected to be useful right away." (Translation: "I'm afraid that someone will decide that I am 'not useful,' and therfore that I am about to get fired.")

"Koff, koff ..."   Tomorrow(!) morning, please have a heart-to-heart talk with your boss.

... and, please: "Listen.*   Learn(!)."

Remember: "if this person did not have great confidence(!) in you, s/he never would have hired you in the first place!"

Do not regard this person as "someone who is disapproving of you," even though you right-now clearly fear that he is. Likewise, do not presume that this person is poised to dump you in favor of some miracle-worker.

The two of you seriously need to talk. ... Tomorrow.

Be totally candid.   Listen.   (I said, "listen!")   Learn...

Mike Robinson
  • 8,111
  • 1
  • 17
  • 27