Mixing
What can I do to improve a difficult coding environment due to lack of documentation? [closed]
Clash Royale CLAN TAG#URR8PPP
.everyoneloves__top-leaderboard:empty,.everyoneloves__mid-leaderboard:empty margin-bottom:0;
up vote
3
down vote
favorite
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.
software-industry software-development
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
asked Jul 26 '16 at 17:35
Silas Mollod
482
closed as off-topic by Chris E, gnat, Jim G., Michael Grubey, alroc Jul 27 '16 at 15:19
This question appears to be off-topic. The users who voted to close gave this specific reason:
- "Real questions have answers. Rather than explaining why your situation is terrible, or why your boss/coworker makes you unhappy, explain what you want to do to make it better. For more information, click here." – Chris E, gnat, Michael Grubey
 |Â
show 1 more comment
up vote
3
down vote
favorite
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.
software-industry software-development
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
asked Jul 26 '16 at 17:35
Silas Mollod
482
closed as off-topic by Chris E, gnat, Jim G., Michael Grubey, alroc Jul 27 '16 at 15:19
This question appears to be off-topic. The users who voted to close gave this specific reason:
- "Real questions have answers. Rather than explaining why your situation is terrible, or why your boss/coworker makes you unhappy, explain what you want to do to make it better. For more information, click here." – Chris E, gnat, Michael Grubey
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
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 ( se-radio.net/2009/11/…). 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 1: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
 |Â
show 1 more comment
up vote
3
down vote
favorite
up vote
3
down vote
favorite
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.
software-industry software-development
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
asked Jul 26 '16 at 17:35
Silas Mollod
482
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.
software-industry software-development
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
asked Jul 26 '16 at 17:35
Silas Mollod
482
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
edited Jul 26 '16 at 18:55
Richard U
77.2k56200307
77.2k56200307
asked Jul 26 '16 at 17:35
Silas Mollod
482
asked Jul 26 '16 at 17:35
Silas Mollod
482
asked Jul 26 '16 at 17:35
Silas Mollod
482
482
closed as off-topic by Chris E, gnat, Jim G., Michael Grubey, alroc Jul 27 '16 at 15:19
This question appears to be off-topic. The users who voted to close gave this specific reason:
- "Real questions have answers. Rather than explaining why your situation is terrible, or why your boss/coworker makes you unhappy, explain what you want to do to make it better. For more information, click here." – Chris E, gnat, Michael Grubey
closed as off-topic by Chris E, gnat, Jim G., Michael Grubey, alroc Jul 27 '16 at 15:19
This question appears to be off-topic. The users who voted to close gave this specific reason:
- "Real questions have answers. Rather than explaining why your situation is terrible, or why your boss/coworker makes you unhappy, explain what you want to do to make it better. For more information, click here." – Chris E, gnat, Michael Grubey
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
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 ( se-radio.net/2009/11/…). 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 1: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
 |Â
show 1 more comment
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
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 ( se-radio.net/2009/11/…). 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 1: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
1
1
Have you spoken to your boss and asked about the possibility of creating some documentation?
– JasonJ
Jul 26 '16 at 18:07
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
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
1
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 ( se-radio.net/2009/11/…). It's just a skill you need to exercise. Have you tried doxygen?
– teego1967
Jul 26 '16 at 23:17
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 ( se-radio.net/2009/11/…). It's just a skill you need to exercise. Have you tried doxygen?
– teego1967
Jul 26 '16 at 23:17
1
1
Possible duplicate of Poor documentation culture
– Jim G.
Jul 27 '16 at 1:00
Possible duplicate of Poor documentation culture
– Jim G.
Jul 27 '16 at 1:00
2
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
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
 |Â
show 1 more comment
4 Answers
4
active
oldest
votes
up vote
8
down vote
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.
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
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
– Richard U
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
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
 |Â
show 4 more comments
up vote
5
down vote
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)
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
suggest improvements |Â
up vote
1
down vote
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.
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
suggest improvements |Â
up vote
0
down vote
"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...
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
suggest improvements |Â
4 Answers
4
active
oldest
votes
4 Answers
4
active
oldest
votes
active
oldest
votes
active
oldest
votes
up vote
8
down vote
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.
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
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
– Richard U
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
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
 |Â
show 4 more comments
up vote
8
down vote
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.
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
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
– Richard U
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
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
 |Â
show 4 more comments
up vote
8
down vote
up vote
8
down vote
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.
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
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.
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
edited Jul 26 '16 at 19:16
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
answered Jul 26 '16 at 18:12
Dan Pichelman
24.5k116682
24.5k116682
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
– Richard U
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
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
 |Â
show 4 more comments
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
– Richard U
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
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
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
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
– Richard U
Jul 26 '16 at 18:50
@JoeStrazzere If it weren't "C" code, I'd agree with you. "C" code is hard to maintain to begin with
– Richard U
Jul 26 '16 at 18:50
4
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
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
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
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
1
1
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
Was troubleshooting and maintenance ever taught?
– gnasher729
Jul 27 '16 at 14:35
 |Â
show 4 more comments
up vote
5
down vote
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)
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
suggest improvements |Â
up vote
5
down vote
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)
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
suggest improvements |Â
up vote
5
down vote
up vote
5
down vote
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)
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
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)
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
answered Jul 26 '16 at 23:55
HorusKol
16.2k63267
16.2k63267
suggest improvements |Â
suggest improvements |Â
up vote
1
down vote
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.
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
suggest improvements |Â
up vote
1
down vote
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.
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
suggest improvements |Â
up vote
1
down vote
up vote
1
down vote
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.
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
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.
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
answered Jul 26 '16 at 19:04
Richard U
77.2k56200307
77.2k56200307
suggest improvements |Â
suggest improvements |Â
up vote
0
down vote
"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...
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
suggest improvements |Â
up vote
0
down vote
"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...
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
suggest improvements |Â
up vote
0
down vote
up vote
0
down vote
"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...
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
"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...
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
answered Jul 27 '16 at 0:44
Mike Robinson
1,9021410
1,9021410
suggest improvements |Â
suggest improvements |Â
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
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 ( se-radio.net/2009/11/…). 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 1: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