Timeline for How can I convince my managers to enforce documentation standards?
Current License: CC BY-SA 4.0
11 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| S Dec 18, 2018 at 17:51 | history | suggested | albert | CC BY-SA 4.0 |
doxygen documentation is at another place
|
| Dec 18, 2018 at 16:57 | review | Suggested edits | |||
| S Dec 18, 2018 at 17:51 | |||||
| Dec 16, 2011 at 20:56 | comment | added | Angelo | +1 on making use of doxygen. A tool like that and some genuine cooperation with an original developer will do much more good than a bunch of comments added after the fact. | |
| Nov 18, 2011 at 21:25 | comment | added | Aerik | Ater spending entirely too long digging, here are some of my own findings: usna.edu/EE/ec361/Lab/documentationstandards.htm , gnu.org/prep/standards/standards.html#Comments , and less authoritative, but very informative: codinghorror.com/blog/2008/07/coding-without-comments.html and kuro5hin.org/story/2004/2/15/71552/7795 | |
| Nov 18, 2011 at 17:37 | comment | added | Aerik | @clamontagne - your link to Google is actually really pretty good... if I can get more stuff like that, it would help. | |
| Nov 18, 2011 at 0:09 | comment | added | Aerik | No, I'm not looking for standards, I'm really looking for authoritative citations and references supporting the use of thorough documentation / commenting. It's the citations and references I'm looking for, not the standards. | |
| Nov 17, 2011 at 20:30 | comment | added | yannis |
There are at least a couple of other questions on programmers that discuss the mindset problems regarding comments, so if the question turns to the subjective it might get closed as a duplicate. As for all programmers should be part of defining the processes that define their job I'd add an exception: those that don't comment their code :)
|
|
| Nov 17, 2011 at 20:12 | comment | added | clamontagne | From what I understood, he is looking for a way to convince management of a process since two teams are of dissimilar mindsets. Standards definitions could help but are readily available en masse on Google. I was more or less catering to his desire to change the minds of management and co-workers. If it is a specification you want, that is something the team should agree upon as a whole. Pointing to one and saying we should use this will only exacerbate the issue, all programmers should be part of defining the processes that define their job. | |
| Nov 17, 2011 at 20:05 | comment | added | Aerik | @YannisRizos - Thank you, yes, that's exactly right... on further reflection, I think maybe clamontagne is highlighting that this my problem (not the question I asked) is difficult because I'm dealing with opinions here at work. But yes, I tried to phrase my question so that it is not subjective - it is exactly as you have summarized. | |
| Nov 17, 2011 at 19:59 | comment | added | yannis |
Actually the issue as described in the question is not subjective. The question does not ask if comments are good or bad, or how to convince people either way, the question specifically asks for authoritative citations / references for documentation / comment standards for source code. I think you should revise your answer to highlight the Google C++ Style Guide you link to (and add some excerpts from it), that's actually in the spirit of the question.
|
|
| Nov 17, 2011 at 19:35 | history | answered | clamontagne | CC BY-SA 3.0 |