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

▶ 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 Introduces Skills for Custom Claude Tasks

Anthropic has unveiled a new feature called Skills, designed to let developers extend Claude with modular, reusable task components.

By Daniel Dominguez

AWS Launches EC2 Capacity Manager for Centralized, Cross-Account Capacity Optimization

Introducing Amazon EC2 Capacity Manager: AWS's new centralized solution for streamlined monitoring and management of EC2 capacity across all accounts and regions. This innovative tool consolidates data into a unified dashboard, enhancing efficiency while reducing operational complexity.

By Steef-Jan Wiggers

Cloudflare Introduces Email Service to Compete with Amazon SES, Resend, and SendGrid

During Cloudflare's recent Birthday Week, the company announced the private preview of its Cloudflare Email Service. This new globally managed service enables developers to send and receive emails directly from Workers using native bindings, without the need for API keys.

By Renato Losio

PyTorch Monarch Simplifies Distributed AI Workflows with a Single-Controller Model

Meta’s PyTorch team has launched Monarch, a framework that simplifies distributed AI workflows across multiple GPUs and machines. It uses a single-controller model to manage computations across a cluster, making large-scale training and reinforcement learning tasks easier while allowing developers to keep their standard PyTorch coding practices.

By Robert Krzaczyński

Airbnb’s Mussel V2: Next-Gen Key Value Storage to Unify Streaming and Bulk Ingestion

Airbnb’s engineering team re-architected its internal key-value storage system, Mussel, to unify streaming and bulk ingestion while simplifying operations, achieving over 100,000 writes per second and sub-25ms read latencies on 100-terabyte tables, while leveraging Kubernetes, Kafka, and a NewSQL backend to improve scalability, reliability, and operational efficiency across its internal services.

By Leela Kumili

© 2025   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service