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

▶ 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

Presentation: Foundation Models for Ranking: Challenges, Successes, and Lessons Learned

Moumita Bhattacharya discusses the evolution of Netflix’s ranking systems, from the multi-model architecture to a Unified Contextual Recommender (UniCoRn). She explains how they built a task-agnostic User Foundation Model to capture long-term member preferences. Learn how they solve system challenges like high-throughput inference and the tradeoff between relevance and personalization.

By Moumita Bhattacharya

Swift Cross-Platform Framework Skip Now Fully Open Source

After three years of development, the team behind Skip, a solution designed to create iOS and Android apps from a single Swift/SwiftUI codebase, has announced their decision to make the product completely and open source, in order to foster adoption and community contribution.

By Sergio De Simone

Railway Highlights the Importance of Logs, Metrics, Traces, and Alerts for Diagnosing System Failure

Railway’s engineering team published a comprehensive guide to observability, explaining how developers and SRE teams can use logs, metrics, traces, and alerts together to understand and diagnose production system failures.

By Craig Risi

Google BigQuery Adds SQL-Native Managed Inference for Hugging Face Models

Google has launched SQL-native managed inference for 180,000+ Hugging Face models in BigQuery. The preview release collapses the ML lifecycle into a unified SQL interface, eliminating the need for separate Kubernetes or Vertex AI management. Key features include automated resource governance via endpoint_idle_ttl and secure identity-based execution using existing data warehouse permissions.

By Steef-Jan Wiggers

Google Introduces TranslateGemma Open Models for Multilingual Translation

Google has released TranslateGemma, a set of open translation models based on the Gemma 3 architecture, offering 4B, 12B, and 27B parameter variants designed to support machine translation across 55 languages and to run on platforms ranging from mobile and edge devices to consumer hardware and cloud accelerators.

By Daniel Dominguez

© 2026   Created by Michael Levin.   Powered by

Badges  |  Report an Issue  |  Terms of Service