Java Magazine, Sept/Oct 2018

ORACLE COM JAVAMAGAZINE SEPTEMBER OCTOBER 2018 06 from the editor Now Ive captured what I wanted to put into code and my most immediate problem is coming up with a good name for the class With the key details captured I can develop it at leisure and write good code that does not need a lot of refactoring If Im a TDD zealot I can start writing a test Either way Im good to go An excellent new book called A Philosophy of Software Design which I review on page 8 advocates using comments as a design step for classes The book is written by John Ousterhout who is the creator of Tcl and Tk and who teaches at Stanford University and earlier at Berkeley when not working at his company which specializes in large project continuous delivery tools Ousterhout suggests when creating a class that you use the following steps which are a significant enlargement of what Ive described above 1 Write the class interface comment 2 Write the interface comments and signatures of the most important public methods but leave the method bodies empty 3 Write comments and declarations for the most important instance variables 4 Fill in the bodies of the methods adding implementation comments as you go along 5 As you discover the need for more methods write the comments before the body According to Ousterhouts experience the benefits are threefold When the code is done its properly commented and the comments are entirely up to date The comment first approach enables you to focus on the abstractions rather than being distracted by the implementation The code will reveal complexity if a method or variable requires a long complex comment it probably needs to be rethought and simplified Thats a lot of benefits Of the things on which to comment the most important in Ousterhouts view are abstractions which are dificult to tease out from reading the implementation code and the reason why the code exists In sum a developer working on your code for the first time should be able to scan the classs comments and have a good idea of what it does and an overview of the most important implementation aspects If this approach appeals to you as it does to me he suggests that you should use it until youre accustomed to writing code this way He believes and I agree that doing so will convert you by delivering cleaner clearer code that is fully commented Andrew Binstock Editor in Chief javamag_ us@ oracle com @ platypusguy PS Many open source projects wish they had more contributors but their code is often so poorly commented and devoid of documentation that its impossible for potential contributors to climb on board Ousterhouts approach would go a long way toward addressing that problem The Best Resource for Modern Cloud Dev The Oracle Developer Gateway is the best place to jump start your modern cloud development skills with free trials downloads tutorials documentation and more Trials Downloads Tutorials Start here developer oracle com developer oracle com developersrule