This is Jim Cooper's Typepad Profile.
Join Typepad and start following Jim Cooper's activity
Join Now!
Already a member? Sign In
Jim Cooper
Recent Activity
@Dianneking71 I stand by my remarks. In particular: Do you expect every programmer to understand the code you've written without checking any documentation? Yes, almost all of the time I do. You may need to understand the problem domain (with or without documentation), but the code should stand alone nearly all the time. If it doesn't then it's bad code. The purpose of comments and documentation is to give you first the whole picture. The code is there for the details. Like I said earlier, I've been in this business a long time. I understand what comments and documentation are for. But I'll say it again, my experience over 20+ years leads me to my opinion that comments and documentation do not make up for bad code. Good code, almost by definition, requires little of either. Maintaining code that has no documentation is far difficult than code with documentation. Not necessarily true. Documentation needs to be maintained along with the code (misleading documentation is worse than useless). That's more work. Forever. For everybody who works on that code. So you should keep documentation to a minimum. This may or may not be zero, but if you can make your code understandable without documentation, that's just got to be better. Most of the time that's possible. FWIW, the best code I've ever seen had no documentation at all (it had unit tests, which do the job better if done well). If code and documentation aren't necessary, why do these popular frameworks (for example frameworks for Java) have to write documentation? I assume you mean comments and documentation, and I didn't say they weren't necessary. However, good frameworks require less documentation. If you have a framework that requires a lot of docs to be understood, I'll argue you don't have a well written framework. I would point out that writing frameworks (ie code that is intended to be widely reused) is much more difficult than "normal" code. Which is why so few of them are very well written :-) Note that useful != well written. Believe me I had handled a big chunk of framework that doesn't even have documentation I've handled a lot of code too, framework and otherwise, over the last 20 some years of professional programming. I'm speaking from that level of experience. You don't fix crappy code with comments and documentation, you need to fix the code. My experience also very strongly correlates lots of comments with very poor code. I rather do extra work documenting than allow my fellow programmer struggle. If I was your fellow programmer, I'd rather you did extra work improving your code so you didn't need to document it :-) Once upon a time, I thought as you did. Way back then, I was told that good code required comments only rarely. I didn't believe it either :-) Maybe there is no point giving people the benefit of your experience, and you have to learn some things the hard way. But I urge you to do a bit of research and give writing code that doesn't require comments and docs a try.
Toggle Commented Feb 15, 2011 on How to Write Without Writing at Coding Horror
@pauldwaite Writing tests before code will get you cleaner code. Then you'll find you won't need all those comments.
Toggle Commented Feb 7, 2011 on How to Write Without Writing at Coding Horror
@ctrlShiftBryan and @Plasticsyntax Maybe my communication skills need updating. I said this: "It's far more important to write clear code, than to write code that needs to be explained by comments and external documents." I've been doing this a long time now, and paying attention while I've done it. I don't really need to be reminded what comments and documentation are for ;-) However, both of you have made comments that I might have made 15 or so years ago, when I had only been in the business a few years. Over my 20+ years doing this job professionally, I have come to the realisation that code that needs very much in the way of comments and/or documentation (in the traditional sense, at least) is bad code. The fact that Joel makes remarks like the one quoted is one measure of his skill. You may need comments in your code, but they should be very rare occurrences. You may need documentation, but if I have to read both your code and your documents to understand any given piece of code, it means I'm going to have to maintain both your code and your documents. This rarely works well, either as a means to understanding, or as a practical matter keeping everything in sync. You should strive to make as much documentation as possible unnecessary. Your code is far more important that either comments or documents, because there is far more of it (I hope!!), and you spend far more time looking at it. Try to write your code without the need for comments. A comment explaining a block of code almost always means there is a method waiting to be extracted. A comment explaining a function/parameter/variable usually means there is a better name waiting to be used. Try to minimise the documents you need. Your code should explain nearly everything about itself. Try and limit documents to things outside of the code, like working environment setup, for example. Critique the documents you already have. Do they still reflect reality? When did anyone last use them? Are these documents helping you deliver great software, or are they an unnecessary burden slowing you down?
Toggle Commented Feb 7, 2011 on How to Write Without Writing at Coding Horror
While I agree communication skills are important, I'm not sure you should be quoting Joel Spolsky. While he sounds a great bloke to work for, I've never seen much evidence he has any great ability to write software. This says it all for me: "By writing clear comments and technical specs, they let other programmers understand their code" It's far more important to write clear code, than to write code that needs to be explained by comments and external documents. But perhaps that what Joel meant, and he just didn't communicate it clearly :-)
Toggle Commented Feb 4, 2011 on How to Write Without Writing at Coding Horror
Jim Cooper is now following The Typepad Team
Feb 4, 2011