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

▶ 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

MySQL Repository Analysis Reveals Declining Development and Shrinking Contributor Base

A recent report has analyzed the repository statistics of the MySQL server to evaluate the project's status, Oracle's commitment to MySQL, and the future of the community edition. Julia Vural, software engineer manager at Percona, writes:

By Renato Losio

From On-Demand to Live : Netflix Streaming to 100 Million Devices in Under 1 Minute

Netflix’s global live streaming platform powers millions of viewers with cloud-based ingest, custom live origin, Open Connect delivery, and real-time recommendations. This article explores the architecture, low-latency pipelines, adaptive bitrate streaming, and operational monitoring that ensure reliable, scalable, and synchronized live event experiences worldwide.

By Leela Kumili

Vitest Team Releases Version 4.0 with Stable Browser Mode and Visual Regression Testing

Vitest 4.0, the Vite testing framework, revolutionizes browser-based testing with stabilizations, built-in visual regression support, and enhanced debugging. With major features like stable Browser Mode and Playwright Traces integration, it streamlines workflows. Developers benefit from a smoother upgrade path and an optimized experience, reinforcing Vitest as a comprehensive testing solution.

By Daniel Curtis

Podcast: Transforming Life Sciences: AI, Vibe Coding, and Drug Development Acceleration

In this podcast, Shane Hastie, Lead Editor for Culture & Methods, spoke to Satish Kothapalli about the transformative impact of AI and vibe coding in life sciences software development, the acceleration of drug development timelines, and the evolving roles of developers in an AI-augmented environment.

By Satish Kothapalli

AWS Lambda Managed Instances: Serverless Flexibility Meets EC2 Cost Models

Unlock the power of AWS Lambda Managed Instances, seamlessly combining serverless functions with Amazon EC2 for optimal performance and cost efficiency. Designed for steady-state workloads, this solution automates instance management, reduces cold starts, and enables multi-concurrency.

By Steef-Jan Wiggers

© 2025   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service