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

▶ 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

The New Data Commons MCP Server Unlocks a Wealth of Public Datasets for AI Developers

Google has recently introduced the Data Commons Model Context Protocol (MCP) Server, a tool that enables AI developers and researchers to easily access the public dataset collection available through Data Commons.

By Sergio De Simone

Google DeepMind Launches Gemini 2.5 Computer Use Model to Power UI-Controlling AI Agents

Google DeepMind has recently released the Gemini 2.5 Computer Use model, a specialized variant of its Gemini 2.5 Pro system designed to enable AI agents to interact directly with graphical user interfaces. The new model allows developers to build agents that can click, type, scroll, and manipulate interactive elements on web pages.

By Robert Krzaczyński

Combining Continuous Delivery with Pair Programming: Lessons Learned

Pair programming and continuous integration can go hand-in-hand. Pushing to main multiple times a day is hard in isolation, leading to delays, large PRs, and merge issues, Ola Hast and Asgaut Mjølne Söderbom mentioned in their talk about continuous delivery with pair programming at QCon London. Pairing enables instant code review, easier refactoring, fewer bugs, and higher team resilience.

By Ben Linders

Azure Container Storage v2.0.0 Goes GA with Major Performance Boost

Microsoft has released Azure Container Storage v2.0.0, introducing significant performance enhancements and architectural simplifications for stateful workloads on Azure Kubernetes Service (AKS). The release focuses on deeper NVMe integration, streamlined user experience, and expanded open-source availability, while removing all service fees beyond underlying storage costs.

By Claudio Masolo

IBM Releases Granite-Docling-258M, a Compact Vision-Language Model for Precise Document Conversion

IBM Research has recently introduced Granite-Docling-258M, a new open-source vision-language model (VLM) designed for high-fidelity document-to-text conversion while preserving complex layouts, tables, equations, and lists.

By Robert Krzaczyński

© 2025   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service