Documentation standards or guidelines?

Does anyone care to share their suggestions for documentation?

I'm asking because I recently had to change a program I wrote more than five years ago. I'd always thought that I've done a good job of documentation. But going through it was difficult. It WAS pulling apart an Excel in CSV format created and saved off by humans, so there was a lot of exception handling. But still . . . .

 - Miek

Views: 140

▶ Reply to This

Replies to This Discussion

Permalink Reply by Adam Davis on April 11, 2014 at 1:29pm

Generally I only put javadocs on public methods, especially ones that are used a lot. I use code comments sometimes, but generally if the code is hard to understand I take that as a "smell" that means you need to break down the code into more methods, refactor, or think about better naming.

▶ Reply to Discussion

RSS

Happy 10th year, JCertif!

Notes

Welcome to Codetown!

Codetown is a social network. It's got blogs, forums, groups, personal pages and more! You might think of Codetown as a funky camper van with lots of compartments for your stuff and a great multimedia system, too! Best of all, Codetown has room for all of your friends.

When you create a profile for yourself you get a personal page automatically. That's where you can be creative and do your own thing. People who want to get to know you will click on your name or picture and…
Continue

Created by Michael Levin Dec 18, 2008 at 6:56pm. Last updated by Michael Levin May 4, 2018.

Looking for Jobs or Staff?

Check out the Codetown Jobs group.

 

Enjoy the site? Support Codetown with your donation.



InfoQ Reading List

Vercel’s Next.js 16: Explicit Caching, Turbopack Stability, and Improved Developer Tooling

Unlock the potential of full-stack web development with Next.js 16! This robust release features revolutionary Cache Components, enhanced routing, and Turbopack as the default bundler for lightning-fast builds. Experience architectural breakthroughs and AI-powered debugging. Upgrade today to optimize performance and streamline your development process!

By Daniel Curtis

JEP 526 Simplifies Deferred Initialization Ahead of JDK 26

JEP 526 introduces Lazy Constants for JDK 26, enhancing developer ergonomics and performance. This feature replaces the earlier Stable Values, simplifying initialization while ensuring thread safety and immutability. With utilities for lazy lists and maps, it promotes efficient resource management, reducing startup costs. Feedback is welcomed to refine this API ahead of a potential future release.

By A N M Bazlur Rahman

Google Introduces Nano Banana Pro with Grounded, Multimodal Image Synthesis

Google has released Nano Banana Pro. The system moves beyond conventional diffusion workflows by tightly coupling image generation with Gemini’s multimodal reasoning stack. The result: visuals that are not only aesthetically pleasing, but structurally, contextually, and informationally accurate.

By Robert Krzaczyński

Presentation: Empathy Driven Platforms: You Build It, Let’s Run It Together

Erin Doyle explains the evolution from siloed IT Ops to the Platform Team model, revealing why the "You Build It, You Run It" principle created new cognitive load. She shares the Empathy-Driven Platforms strategy - the ultimate attack against engineering roadblocks. Discover ways platform teams can build empathy, foster psychological safety, and adopt a product mindset.

By Erin Doyle

Accessibility with Interactive Components at React Advanced Conf

Dynamic React speaker Aurora Scharff captivated attendees at React Advanced 2025 with her talk on "Building Interactive Async UI with React 19 and Ariakit." She showcased ARIAKit, an open-source accessibility library that empowers developers to create WCAG-compliant components effortlessly, blending modern React patterns with customizable, accessible UI primitives.

By Daniel Curtis

© 2025   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service