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: 144

▶ 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

Article: One Cache to Rule Them All: Handling Responses and In-Flight Requests with Durable Objects

Traditional caching fails to stop "thundering herds" where multiple clients trigger the same work during a miss. This article proposes using Cloudflare Durable Objects to treat in-flight work and finished results as two states of one cache entry. By routing to a single owner, systems eliminate redundant tasks. This pattern replaces complex locks with simple promises, simplifying the system design.

By Gabor Koos

.NET 10 Becomes Available on AWS Lambda as Managed Runtime and Base Image

Amazon Web Services has announced that AWS Lambda now supports the creation of serverless applications using .NET 10. With this update, developers can use .NET 10 both as a managed runtime and as a container-based image when building and running Lambda functions.

By Almir Vuk

HTML Invoker Commands Achieve Baseline Support Across All Major Browsers

The HTML Invoker Commands API revolutionizes web interactivity by enabling developers to create button controls for popovers and dialogs without JavaScript. Supported across major browsers, it streamlines user experience and enhances page load speeds. This declarative approach fosters accessibility and empowers developers, marking a significant step towards reduced JavaScript dependencies.

By Daniel Curtis

Java News Roundup: Oracle Critical Patch Update, Grizzly 5, Payara Platform, GraalVM, Liberica JDK

This week's Java roundup for January 19th, 2026, features news highlighting: JEP 527, Post-Quantum Hybrid Key Exchange for TLS 1.3, targeted for JDK 27; GlassFish Grizzly 5.0; the quarterly release of the Oracle Critical Patch Update (CPU) Advisory; the January 2026 edition of the Payara Platform; and maintenance releases of Liberica JDK, GraalVM, OpenXava and Ktor.

By Michael Redlich

OpenAI and Anthropic Introduce Healthcare-Focused AI Platforms

OpenAI and Anthropic have announced new healthcare-oriented AI offerings that extend their models beyond general conversational use and into regulated clinical and life sciences environments. Both releases emphasize technical integration, interoperability, and governance, reflecting a shift toward AI systems designed to operate directly within existing healthcare infrastructure.

By Robert Krzaczyński

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service