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

▶ 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

Anthropic Releases Claude Mythos Preview with Cybersecurity Capabilities but Withholds Public Access

Anthropic has introduced Claude Mythos Preview, its most advanced AI model, improving significantly in reasoning, coding, and cybersecurity. Unlike previous releases, it will not be publicly available. Access is limited to a consortium of tech companies through Project Glasswing. Internal tests revealed the model's ability to discover critical security flaws effectively.

By Daniel Curtis

Java News Roundup: JDK 27 Release Schedule, Hibernate, LangChain4j, Keycloak, Helidon, Junie CLI

This week's Java roundup for April 6th, 2026, features news highlighting: the fifth preview of Primitive Types in Patterns, instanceof and switch; the proposed release schedule for JDK 27; point releases of Hibernate, LangChain4j, Keycloak and Google ADK for Java; a maintenance release of Helidon; a CVE in Spring Cloud Gateway; and the Junie CLI integrated in JetBrains IDEs.

By Michael Redlich

GitHub Copilot CLI Reaches General Availability

GitHub has launched Copilot CLI into general availability, bringing generative AI directly to the terminal. Integrated with the GitHub CLI, it offers natural language command suggestions and code explanations. Recent updates introduce "agentic" workflows with Autopilot mode and GPT-5.4 support, alongside new enterprise telemetry for tracking usage across development teams.

By Mark Silvester

Etsy Migrates 1000-Shard, 425 TB MySQL Sharding Architecture to Vitess

The Etsy engineering team recently described how the company migrated its long-running MySQL sharding infrastructure to Vitess. The transition moved shard routing from Etsy’s internal systems to Vitess using vindexes, enabling capabilities such as resharding data and sharding previously unsharded tables.

By Renato Losio

Presentation: Latency: the Race to Zero...Are We There Yet?

Amir Langer discusses the evolution of latency reduction, from the Pony Express to modern hardware. He explains how separation of concerns - decoupling business logic from I/O - and tools like Aeron and the Disruptor achieve single-digit microsecond speeds. He shares insights into replicated state machines, consensus protocols like Raft, and the future of low-latency sequencer architectures.

By Amir Langer

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service