3
votes
2answers
161 views

How to do documentation for code and why is software (often) poorly documented?

There are some good examples of well-documented code out there, such as java api. But, a lot of code in public projects such as git and internal projects of companies is poorly documented and not very ...
3
votes
2answers
178 views

Is it customary for software companies to forbid code authors from taking credit for their work? do code authors have a say?

The company I work for has decided that the source code for a set of tools they make available to customers is also going to be made available to those customers. Since I am the author of that source ...
5
votes
5answers
252 views

Hyperlinked, externalized source code documentation

Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive ...
8
votes
4answers
415 views

Should we be looking out for lying code?

This is referring to a discussion in an answer and the comments of this question: What's with the aversion to documentation in the industry?. The answer claimed that "code can't lie" and thus ...
1
vote
0answers
88 views

Is there a unified source code documentation generator? [duplicate]

I'm currently working on a client's project that involves programming in multiple languages. It has gotten to the point where the amount of source code for each language has grown to such a large ...
6
votes
3answers
176 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
4
votes
5answers
931 views

How to make sure the application source code has a proper documentation for new programmers? [duplicate]

Possible Duplicate: How much documentation is enough? Do you know how the big IT company like IBM, Microsoft, or google make sure their application source code has proper documentation for ...
9
votes
4answers
2k views

Prepare source code handover plan

Our company is about to acquire a source code of a huge product. What are thing to take into consideration when the handover starts, to make sure we have everything and be capable to maintain that ...
20
votes
5answers
838 views

How-to convince company to start documenting for legacy software [duplicate]

It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
7
votes
6answers
2k views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
5
votes
6answers
502 views

How complex is the documentation you write?

In a book I'm reading there is a chapter on documentation for your code. The book is about PHP and described some easy methods but also going for some complicated and time consuming methods (xml, xsl) ...