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

▶ 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

Have I Been Pwned 2.0 Adds New Tools for Data Breach Monitoring

Have I Been Pwned (HIBP) - the widely used data breach notification service created by security expert Troy Hunt has launched a major front-end redesign in version 2.0, introducing several new features aimed at improving how individuals and organizations monitor breach exposure.

By Matt Foster

Microsoft Open Sources the Github Copilot Chat Extension

At its Build 2025 conference, Microsoft announced plans to open source over the next few months the code behind the GitHub Copilot Chat extension under the MIT license and refactor core AI capabilities directly into the main VS Code codebase. The move, if completed, may affect the ability of current for-pay AI code editors to compete purely on features.

By Bruno Couriol

Google Releases LMEval, an Open-Source Cross-Provider LLM Evaluation Tool

LMEval aims to help AI researchers and developers compare the performance of different large language models. Designed to be accurate, multimodal, and easy to use, LMEval has already been used to evaluate major models in terms of safety and security.

By Sergio De Simone

Azure AI Search Unveils Agentic Retrieval for Smarter Conversational AI

Microsoft’s Azure AI Search unveils agentic retrieval, a cutting-edge query engine that enhances conversational AI answer relevance by up to 40%. This dynamic system leverages conversation history and parallel subquery execution, paving the way for sophisticated knowledge retrieval. Currently in public preview, it offers adaptive search strategies tailored for evolving enterprise needs.

By Steef-Jan Wiggers

OpenSearch 3.0 Now Generally Available, with a Focus on Vector Database Performance and Scalability

The OpenSearch Software Foundation has announced the general availability of OpenSearch 3.0, the first major release in three years and the first since the project joined the Linux Foundation. This version introduces native support for the Model Context Protocol (MCP), along with pull-based data ingestion and gRPC support, aimed at improving scalability and integration.

By Renato Losio

© 2025   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service