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

QCon London 2026: Your Multi-Cloud Strategy Is a Product Problem — Treat It Like One

JP Morgan Chase engineers Luis Albinati and Surabhi Mahajan argued that multi-cloud complexity can't be solved with engineering alone. Speaking at QCon London, they showed how treating multi-cloud as a product with capability mapping, demand governance, and defined users tames the chaos.

By Steef-Jan Wiggers

AI Is Amplifying Software Engineering Performance, Says the 2025 DORA Report

Artificial intelligence is rapidly reshaping the way software is built, but its impact is more nuanced than many organizations expected. The 2025 DevOps Research and Assessment (DORA) report, titled State of AI-Assisted Software Development, finds that AI does not automatically improve software delivery performance.

By Craig Risi

QCon London 2026: All Tech Debt is Not Created Equal

Joy Ebertz, Principal Engineer at Imprint, presented at QCon London 2026 a groundbreaking framework for prioritizing technical debt amidst rapid AI-driven code production. By challenging perfectionist mindsets, her six-question approach helps teams assess impact and costs, ensuring focus on vital debt. Jot emphasizes translating tech decisions into financial terms, empowering smarter engineering.

By Daniel Curtis

QCon London 2026: Behind Booking.com's AI Evolution: The Unpolished Story

Jabez Eliezer Manuel, Senior Principal Engineer at Booking.com, presented “Behind Booking.com's AI Evolution: The Unpolished Story” at QCon London 2026. Manuel discussed how Booking.com has evolved over the past 20 years and the challenges they faced on their journey to incorporate AI.

By Michael Redlich

Google Open-Sources the Common Expression Language for Python

Google has open sourced CEL-expr-python, a Python implementation of the Common Expression Language (CEL), a non-Turing complete embedded policy and expression language designed for simplicity, speed, safety, and portability.

By Sergio De Simone

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service