Mixing
What can I do to understand a medium-sized project with no documentation? [closed]
Clash Royale CLAN TAG#URR8PPP
.everyoneloves__top-leaderboard:empty,.everyoneloves__mid-leaderboard:empty margin-bottom:0;
up vote
2
down vote
favorite
I recently finished college and started working at a software company. They have a main application (consisting of over 2000, maybe 3000 source code files), written mainly in Java and Flex(Adobe Flash Player). It is a program intended to be used by some companies in the service sector to replace their human workforce with something that can be done easier via a computer (like tracking workers, assigning work to them and many more other things). This program was developed about 5 years ago and it is still updated (by fixing bugs and adding new features as new clients want to use this program).
Because I have worked in the past (an year ago) as an intern, my first assignment was to write an algorithm that handles some events automatically (which can also be handled manually by an operator that uses this application). Problem is, the code isn't documented, every source code file ranged from about 100 to over 2000 lines of code, and it is very annoying and hard to understand how to do some things (even when I know, as a pseudo code, what my algorithm looks like). Because of this I have to ask a colleague of my age who has worked for over an year here, and when he doesn't know, I have to ask a senior, which is pretty much occupied and doesn't have too much time to answer. Mainly I am stuck by looking into many source code files and trying to understand what it goes there and trying to find code I can use to make this algorithm.
I am pretty sad because of this, and was wondering if having a medium-sized application (a long-sized in my opinion may have 100k+ files or so) with no documented source code (no comments in files) (actually there are a few files, usually very long ones, who have about 5-8 lines of comment in total) is common in industry, and it is actually my duty to try to do reverse engineering on their code to understand how to do things. If so, what should I do to understand better this application, without annoying my colleagues a lot of times? I have tried to operate this application manually, but there are many events and things happening there I don't understand and I think an operator for a company that buys this program is trained to know how to use it. If not, should I try to avoid such workplaces in the future (and how do I know they follow this trend)?
software-industry software-development
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
asked Aug 20 '16 at 19:45
shul
164
closed as off-topic by Lilienthal♦, Jim G., gnat, mcknz, Masked Man♦ Aug 21 '16 at 4:26
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." – Jim G., gnat
 |Â
show 2 more comments
up vote
2
down vote
favorite
I recently finished college and started working at a software company. They have a main application (consisting of over 2000, maybe 3000 source code files), written mainly in Java and Flex(Adobe Flash Player). It is a program intended to be used by some companies in the service sector to replace their human workforce with something that can be done easier via a computer (like tracking workers, assigning work to them and many more other things). This program was developed about 5 years ago and it is still updated (by fixing bugs and adding new features as new clients want to use this program).
Because I have worked in the past (an year ago) as an intern, my first assignment was to write an algorithm that handles some events automatically (which can also be handled manually by an operator that uses this application). Problem is, the code isn't documented, every source code file ranged from about 100 to over 2000 lines of code, and it is very annoying and hard to understand how to do some things (even when I know, as a pseudo code, what my algorithm looks like). Because of this I have to ask a colleague of my age who has worked for over an year here, and when he doesn't know, I have to ask a senior, which is pretty much occupied and doesn't have too much time to answer. Mainly I am stuck by looking into many source code files and trying to understand what it goes there and trying to find code I can use to make this algorithm.
I am pretty sad because of this, and was wondering if having a medium-sized application (a long-sized in my opinion may have 100k+ files or so) with no documented source code (no comments in files) (actually there are a few files, usually very long ones, who have about 5-8 lines of comment in total) is common in industry, and it is actually my duty to try to do reverse engineering on their code to understand how to do things. If so, what should I do to understand better this application, without annoying my colleagues a lot of times? I have tried to operate this application manually, but there are many events and things happening there I don't understand and I think an operator for a company that buys this program is trained to know how to use it. If not, should I try to avoid such workplaces in the future (and how do I know they follow this trend)?
software-industry software-development
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
asked Aug 20 '16 at 19:45
shul
164
closed as off-topic by Lilienthal♦, Jim G., gnat, mcknz, Masked Man♦ Aug 21 '16 at 4:26
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." – Jim G., gnat
3
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
1
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
2
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48
 |Â
show 2 more comments
up vote
2
down vote
favorite
up vote
2
down vote
favorite
I recently finished college and started working at a software company. They have a main application (consisting of over 2000, maybe 3000 source code files), written mainly in Java and Flex(Adobe Flash Player). It is a program intended to be used by some companies in the service sector to replace their human workforce with something that can be done easier via a computer (like tracking workers, assigning work to them and many more other things). This program was developed about 5 years ago and it is still updated (by fixing bugs and adding new features as new clients want to use this program).
Because I have worked in the past (an year ago) as an intern, my first assignment was to write an algorithm that handles some events automatically (which can also be handled manually by an operator that uses this application). Problem is, the code isn't documented, every source code file ranged from about 100 to over 2000 lines of code, and it is very annoying and hard to understand how to do some things (even when I know, as a pseudo code, what my algorithm looks like). Because of this I have to ask a colleague of my age who has worked for over an year here, and when he doesn't know, I have to ask a senior, which is pretty much occupied and doesn't have too much time to answer. Mainly I am stuck by looking into many source code files and trying to understand what it goes there and trying to find code I can use to make this algorithm.
I am pretty sad because of this, and was wondering if having a medium-sized application (a long-sized in my opinion may have 100k+ files or so) with no documented source code (no comments in files) (actually there are a few files, usually very long ones, who have about 5-8 lines of comment in total) is common in industry, and it is actually my duty to try to do reverse engineering on their code to understand how to do things. If so, what should I do to understand better this application, without annoying my colleagues a lot of times? I have tried to operate this application manually, but there are many events and things happening there I don't understand and I think an operator for a company that buys this program is trained to know how to use it. If not, should I try to avoid such workplaces in the future (and how do I know they follow this trend)?
software-industry software-development
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
asked Aug 20 '16 at 19:45
shul
164
I recently finished college and started working at a software company. They have a main application (consisting of over 2000, maybe 3000 source code files), written mainly in Java and Flex(Adobe Flash Player). It is a program intended to be used by some companies in the service sector to replace their human workforce with something that can be done easier via a computer (like tracking workers, assigning work to them and many more other things). This program was developed about 5 years ago and it is still updated (by fixing bugs and adding new features as new clients want to use this program).
Because I have worked in the past (an year ago) as an intern, my first assignment was to write an algorithm that handles some events automatically (which can also be handled manually by an operator that uses this application). Problem is, the code isn't documented, every source code file ranged from about 100 to over 2000 lines of code, and it is very annoying and hard to understand how to do some things (even when I know, as a pseudo code, what my algorithm looks like). Because of this I have to ask a colleague of my age who has worked for over an year here, and when he doesn't know, I have to ask a senior, which is pretty much occupied and doesn't have too much time to answer. Mainly I am stuck by looking into many source code files and trying to understand what it goes there and trying to find code I can use to make this algorithm.
I am pretty sad because of this, and was wondering if having a medium-sized application (a long-sized in my opinion may have 100k+ files or so) with no documented source code (no comments in files) (actually there are a few files, usually very long ones, who have about 5-8 lines of comment in total) is common in industry, and it is actually my duty to try to do reverse engineering on their code to understand how to do things. If so, what should I do to understand better this application, without annoying my colleagues a lot of times? I have tried to operate this application manually, but there are many events and things happening there I don't understand and I think an operator for a company that buys this program is trained to know how to use it. If not, should I try to avoid such workplaces in the future (and how do I know they follow this trend)?
software-industry software-development
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
asked Aug 20 '16 at 19:45
shul
164
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
edited Aug 21 '16 at 4:26
Monica Cellio♦
43.6k17114191
43.6k17114191
asked Aug 20 '16 at 19:45
shul
164
asked Aug 20 '16 at 19:45
shul
164
asked Aug 20 '16 at 19:45
shul
164
164
closed as off-topic by Lilienthal♦, Jim G., gnat, mcknz, Masked Man♦ Aug 21 '16 at 4:26
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." – Jim G., gnat
closed as off-topic by Lilienthal♦, Jim G., gnat, mcknz, Masked Man♦ Aug 21 '16 at 4:26
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." – Jim G., gnat
3
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
1
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
2
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48
 |Â
show 2 more comments
3
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
1
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
2
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48
3
3
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
1
1
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
2
2
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48
 |Â
show 2 more comments
4 Answers
4
active
oldest
votes
up vote
2
down vote
accepted
Amount and quality of internal documentation varies widely.
Given that you're in this situation now, though, your goals should be:
- Get unblocked. Figure out how to figure out this body of code.
- Try to improve practices.
- Filter for this in future interviews if you don't want to do 1 and 2 again.
1. Get unblocked
As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.
If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.
2. Improve practices
Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.
Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.
Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.
That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.
3. Filter future jobs
If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.
With those caveats... here are some types of questions you can ask technical interviewers:
Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.
If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.
Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.
I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.
edited Apr 13 '17 at 12:48
Community♦
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
suggest improvements |Â
up vote
3
down vote
You should have got a "Code walk through" with an expert at the start of your job.
If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.
Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")
answered Aug 20 '16 at 20:23
arved
22628
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
suggest improvements |Â
up vote
2
down vote
It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.
It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.
There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
suggest improvements |Â
up vote
1
down vote
'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.
Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
suggest improvements |Â
4 Answers
4
active
oldest
votes
4 Answers
4
active
oldest
votes
active
oldest
votes
active
oldest
votes
up vote
2
down vote
accepted
Amount and quality of internal documentation varies widely.
Given that you're in this situation now, though, your goals should be:
- Get unblocked. Figure out how to figure out this body of code.
- Try to improve practices.
- Filter for this in future interviews if you don't want to do 1 and 2 again.
1. Get unblocked
As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.
If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.
2. Improve practices
Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.
Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.
Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.
That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.
3. Filter future jobs
If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.
With those caveats... here are some types of questions you can ask technical interviewers:
Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.
If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.
Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.
I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.
edited Apr 13 '17 at 12:48
Community♦
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
suggest improvements |Â
up vote
2
down vote
accepted
Amount and quality of internal documentation varies widely.
Given that you're in this situation now, though, your goals should be:
- Get unblocked. Figure out how to figure out this body of code.
- Try to improve practices.
- Filter for this in future interviews if you don't want to do 1 and 2 again.
1. Get unblocked
As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.
If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.
2. Improve practices
Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.
Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.
Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.
That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.
3. Filter future jobs
If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.
With those caveats... here are some types of questions you can ask technical interviewers:
Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.
If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.
Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.
I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.
edited Apr 13 '17 at 12:48
Community♦
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
suggest improvements |Â
up vote
2
down vote
accepted
up vote
2
down vote
accepted
Amount and quality of internal documentation varies widely.
Given that you're in this situation now, though, your goals should be:
- Get unblocked. Figure out how to figure out this body of code.
- Try to improve practices.
- Filter for this in future interviews if you don't want to do 1 and 2 again.
1. Get unblocked
As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.
If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.
2. Improve practices
Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.
Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.
Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.
That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.
3. Filter future jobs
If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.
With those caveats... here are some types of questions you can ask technical interviewers:
Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.
If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.
Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.
I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.
edited Apr 13 '17 at 12:48
Community♦
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
Amount and quality of internal documentation varies widely.
Given that you're in this situation now, though, your goals should be:
- Get unblocked. Figure out how to figure out this body of code.
- Try to improve practices.
- Filter for this in future interviews if you don't want to do 1 and 2 again.
1. Get unblocked
As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.
If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.
2. Improve practices
Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.
Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.
Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.
That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.
3. Filter future jobs
If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.
With those caveats... here are some types of questions you can ask technical interviewers:
Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.
If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.
Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.
I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.
edited Apr 13 '17 at 12:48
Community♦
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
edited Apr 13 '17 at 12:48
Community♦
1
edited Apr 13 '17 at 12:48
Community♦
1
edited Apr 13 '17 at 12:48
Community♦
1
1
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
answered Aug 21 '16 at 4:22
Monica Cellio♦
43.6k17114191
43.6k17114191
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
suggest improvements |Â
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
Every answer here was helpful, but yours was the most complete of them all. Thank you for your advices, and if you have some others (or maybe some useful links) please share them. I really look forward into finding a good company that cares both of its employees and its source code. Sadly, there is no code walkthrough or documentation, (my seniors said that), so all I can do is ask colleagues, try to understand it myself and take notes.
– shul
Aug 21 '16 at 8:06
1
1
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
@shul glad to help. The best way to get additional input on this site is to edit the question along the lines of what was suggested in the comments, so it can be reopened and more people can answer. See also the links in the "on hold" notice.
– Monica Cellio♦
Aug 21 '16 at 17:08
suggest improvements |Â
up vote
3
down vote
You should have got a "Code walk through" with an expert at the start of your job.
If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.
Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")
answered Aug 20 '16 at 20:23
arved
22628
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
suggest improvements |Â
up vote
3
down vote
You should have got a "Code walk through" with an expert at the start of your job.
If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.
Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")
answered Aug 20 '16 at 20:23
arved
22628
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
suggest improvements |Â
up vote
3
down vote
up vote
3
down vote
You should have got a "Code walk through" with an expert at the start of your job.
If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.
Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")
answered Aug 20 '16 at 20:23
arved
22628
You should have got a "Code walk through" with an expert at the start of your job.
If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.
Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")
answered Aug 20 '16 at 20:23
arved
22628
answered Aug 20 '16 at 20:23
arved
22628
answered Aug 20 '16 at 20:23
arved
22628
answered Aug 20 '16 at 20:23
arved
22628
22628
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
suggest improvements |Â
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
Thanks. These are 2 useful questions to ask during an interview.
– shul
Aug 20 '16 at 20:38
2
2
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
You need a third question as well: how often do you lie to interview candidates? ;)
– Masked Man♦
Aug 21 '16 at 6:43
suggest improvements |Â
up vote
2
down vote
It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.
It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.
There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
suggest improvements |Â
up vote
2
down vote
It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.
It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.
There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
suggest improvements |Â
up vote
2
down vote
up vote
2
down vote
It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.
It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.
There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.
It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.
There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
answered Aug 20 '16 at 20:47
Kilisi
94.3k50216374
94.3k50216374
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
suggest improvements |Â
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Why would this be done on purpose? What is there to gain by doing this?
– shul
Aug 20 '16 at 21:00
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
Someone might thing it makes them irreplacable if there are no comments in their code whatsoever. Obviously that's the first person you get rid off :-)
– gnasher729
Aug 20 '16 at 21:31
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
@shul two reasons that I use, firstly, test how good the bigmouth new guy actually is, secondly the code will be seen by clients and I don't want them reverse engineering it rather than buying a product off me. I actually comment most of my code in a different language which is unlikely to be known and isn't documented in google translate and stuff. I can think of other reasons, but those are the ones I use.
– Kilisi
Aug 20 '16 at 21:35
suggest improvements |Â
up vote
1
down vote
'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.
Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
suggest improvements |Â
up vote
1
down vote
'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.
Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
suggest improvements |Â
up vote
1
down vote
up vote
1
down vote
'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.
Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.
Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
answered Aug 20 '16 at 22:49
PeteCon
12.5k43552
12.5k43552
suggest improvements |Â
suggest improvements |Â
3
Is it common for medium-sized source code applications not to be documented? Sadly, yes. Most "programmers" are not programmer enough to understand why docs are necessary.
– deviantfan
Aug 20 '16 at 20:08
and it is actually my duty to try to do reverse engineering on their code to understand how to do things Other than saying "No, I quit", you can't do anything else.
– deviantfan
Aug 20 '16 at 20:10
1
Isn't this more of a programming question? This doesn't feel on-topic here and is probably too broad even on Software Engineering given the ambiguity in "medium-sized application" and when you consider something to be documented.
– Lilienthal♦
Aug 20 '16 at 21:31
I consider something to be documented when either most of the steps involving high usage of code is explained in comments, or there is a document (or web page) which explains what each function does, like docs.oracle.com/javase/7/docs/api .
– shul
Aug 20 '16 at 21:41
2
For a problem of the scale you are describing, you need documentation outside the source code more than code comments. You need some kind of architecture documentation.
– Eric
Aug 20 '16 at 21:48