Like others here I feel poor documentation is the most painful issue. Languages, IDEs, operating systems, and frameworks all have major problems with this. There is a very old joke that goes: "When they finally teach computers to understand English, they will realize that programmers can't speak English." There are reasons for this. To succeed, programmers must reduce complex ideas to mental symbols that can be manipulated without articulation. It is hard to achieve this ability and painful to go in the reverse direction.
There are times when programmers evade the responsibility to document their efforts and even times when so-called documentation is a patent fraud, a pretense at documentation. In general failure to adequately document your work is un-professional and degrades the profession. Just coding is not professional it is a subprofessional technical career.
To succeed, programmers must reduce complex ideas to mental symbols that can be manipulated without articulation. It is hard to achieve this ability and painful to go in the reverse direction.
I wonder if I never achieved that ability, which is the reason that I pretty much always articulate coding ideas, in English, in my head. Maybe that's why I document so much better than other devs I've seen. ;p
It's sometimes obvious that it isn't the best approach to thinking through some things though. Cue paragraphs of explanation for a one line math formula.
Comments
Like others here I feel poor documentation is the most painful issue. Languages, IDEs, operating systems, and frameworks all have major problems with this. There is a very old joke that goes: "When they finally teach computers to understand English, they will realize that programmers can't speak English." There are reasons for this. To succeed, programmers must reduce complex ideas to mental symbols that can be manipulated without articulation. It is hard to achieve this ability and painful to go in the reverse direction.
There are times when programmers evade the responsibility to document their efforts and even times when so-called documentation is a patent fraud, a pretense at documentation. In general failure to adequately document your work is un-professional and degrades the profession. Just coding is not professional it is a subprofessional technical career.
I wonder if I never achieved that ability, which is the reason that I pretty much always articulate coding ideas, in English, in my head. Maybe that's why I document so much better than other devs I've seen. ;p
It's sometimes obvious that it isn't the best approach to thinking through some things though. Cue paragraphs of explanation for a one line math formula.
It may not be an inability. It may be that you have a well disciplined way of working. It is something to be admired.
That's insightful. What would you say the most important documentation is?
Saying that it's whatever I'm working on at the moment is not really a poor answer. It's all important to someone at sometime.
interesting, thanks! do you have any example of great documentation?