Your Code is Not Self Documenting

Re:Your Code is Not Self Documenting by whyme on Sunday January 09, 2011 @10:33PM (#2087338)

  "Almost all programmers type fast, say 400+ characters  
   per minute. So how long does it take to write one two 
   lines of simple text explaining your code? 15 seconds 
   maybe?"

OMG - is this true? He can't be talking about code - can he? I'm lone programmer & self taught. If it's true I must really suck because it takes me so much longer it's not funny. LoL - I have to stop and think, for minutes, almost all the time.

[ Parent | on HN ]

Re:Your Code is Not Self Documenting by nostrademons on Sunday January 09, 2011 @10:43PM (#2087368)

I don't usually have to stop and think for documentation, though. That's the idea - you're just putting down what's already in your head so that the maintainer can read it.

That said, I usually find that the documentation I write ends up becoming out-of-date about 5 minutes after I write it, because code changes in the process of writing it down. I might write down a docstring to clarify my thoughts, but then the function I actually write doesn't do exactly what I thought it would, and I have to go back and remove or cleanup the docstring later.

[ Parent | on HN ]

Re:Your Code is Not Self Documenting by bobds on Sunday January 09, 2011 @10:48PM (#2087377)

Programmers who type that fast might not have enough time to think. Typing speed is never the bottleneck.

[ Parent | on HN ]

Re:Your Code is Not Self Documenting by 5teev on Monday January 10, 2011 @01:51AM (#2087747)

True, one of the most accomplished programmers I know merely hunts and pecks on the keyboard.

[ Parent | on HN ]