Lesson 12: Comments and Docs: The Lore of Middleware-earth
[CFL2M] Save on ColdFusion Projects with These Commenting Hacks
*Note: This content is from our free ColdFusion Legacy 2 Modernization E-Course [CFL2M]. Interested in getting the full course? Click here to sign up.
Many CIOs and devs don’t know the difference between good comments and destructive orc-style comments.
The determining question: Do your comments make it easier or harder for another human to read?
Today’s lesson will focus on commenting and documenting and how to use them properly.
Before we dive into that, quick electronic high-five to those of you who did last email’s Aragorn Action Step and downloaded Git or BitBucket! Way to go, you’re so cool you’re almost as cold as ColdFusion itself!
Now- about 50% of the CF apps we look at don’t even have any comments at all. So if you’re using comments, just know that you’re ahead of half of the pack.
Why is it important to have comments or documentation?
Good comments make it easier for other humans to understand the code and avoid mistakes or assumptions.
The other human could be a team member, a CF consultant, or it could be you in 6 months when the code isn’t as fresh and you forgot some things.
Good comments live at the top of the function or piece of code and say: “This is what it’s supposed to do and here are the biz rules we’re supposed to follow, these are the assumptions we’re making.”
Destructive comments are any comments that make it HARDER for the human to read and understand. Here are some destructive comments that we often come across:
- One comment on each line that repeats the code. The code itself should be self-commenting, using variable names that make sense. You don’t need to comment on every line.
- Outdated comments. The code says one thing and the comments say another. The comments may be talking about an old version of the app and features it used to have and they didn’t update it.
- “I wrote really bad code here, watch out” → these comments are sort of useful… but wouldn’t it be better to take the time to actually make the code easier to understand?
- Hard-code values: Some devs add some magic number in the code and comment “This magic number means ____.” It would be better to put that in a variable or a constant with an appropriate name.
5 Strategies for Effective Documentation
1. Set Clear Guidelines: Outline specific practices for version control, change management, coding standards, deployment, and security to ensure uniformity across your project.
2. Highlight Special Requirements: Identify and document any unique project needs, including compliance standards and security constraints, early in the process.
3. Prioritize Documentation Updates: Integrate regular reviews and updates of documentation into your development cycle to keep all project materials current.
4. Utilize Efficient Tools: Adopt documentation and collaboration tools to simplify the management process, encouraging team participation and accessibility.
5. Team Education: Stress the importance of comprehensive documentation through ongoing team education on best practices and tool usage.
I’m not going to beg you the way Frodo begs Gandalf for guidance in the Mines of Moria, but I strongly advise you to carefully consider your approach to commenting.
It’s not just about making your code understandable; it’s about ensuring that your entire development process is transparent, manageable, and secure for anyone who might work on it now or in the future.
To quote Benjamin Franklin (who probably would have thrived using CF had he encountered it), "An ounce of prevention is worth a pound of cure."
Aragorn Action Step: Pretend that you are a new developer who has not seen your CF code before! Review how good your comments are.
Bonus steps: Check the list above, do you have any gaps? Is there anything else you need to document? What’s your goal for changing their commenting? Think about these questions and then draft an initial plan.
If you want our help with this, please click here and we can set up a chat to see if it’s a good fit to work together.
Happy commenting!
Michaela Light,
CEO TeraTech
PS Next time, I’ll share our three favorite provisioning tools. Be on the lookout; you won’t want to miss it. You’re almost done with this email course. Get excited 🙂
