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

▶ 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

Uber Automates Design Documentation with Agentic Systems

Uber’s uSpec uses AI agents and the Figma Console MCP to automate design specs, cutting documentation time from weeks to minutes. Integrated with the Michelangelo platform, it uses a GenAI Gateway for PII redaction, ensuring data stays local. This reflects a 2026 industry shift between Uber’s "Visual-First" Figma workflow and a "Guide-First" approach favored by developers using agentic IDEs.

By Patrick Farry

Revenium Unveils Tool Registry to Expose the True Cost of AI Agents

Revenium has announced the general availability of its Tool Registry, a new capability designed to give enterprises a complete, end-to-end view of what their AI agents actually cost.

By Craig Risi

AI Coding Assistants Haven’t Sped up Delivery Because Coding Was Never the Bottleneck

Agoda recently published an observation arguing that while AI coding tools have measurably raised individual developer output, the resulting velocity gains at the project level have been surprisingly modest, because coding was never the real bottleneck. The post claims that the bottleneck has shifted upstream to specification and verification because these areas require human judgment.

By Eran Stiller

QCon London 2026: Ethical AI is an Engineering Problem

At QCon London 2026, Clara Higuera, responsible AI program lead at BBVA, presented how many of the risks associated with AI systems are fundamentally engineering challenges rather than purely governance or policy issues.

By Daniel Dominguez

Presentation: From Friction to Flow: How Great DevEx Makes Everything Awesome

Nicole Forsgren discusses the "AI Productivity Paradox", explaining why generating code faster often makes deployment bottlenecks more expensive. She shares the DevEx framework to help architects and leaders systematically remove friction. Learn how to use DORA metrics and RICE prioritization to make a data-driven case for platform health.

By Nicole Forsgren

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service