• Home
    • Phil-Wilkins.uk
  • About
    • Presenting Activities
    • http://phil-wilkins.uk/
    • LinkedIn
  • Books & Publications
    • Fluentd, Unified Logging With
      • Unified Logging with Fluentd – Book
      • Fluentd Book Resources
      • Log Generator
    • API Platform
      • API Useful Resources
    • Oracle Integration
      • Book Website
      • Useful Reading Sources
  • Mindmaps etc
    • Mindmaps Index
    • Patterns Sources
    • Oracle Integration Site

Phil (aka MP3Monster)'s Blog

~ from Technology to Music

Phil (aka MP3Monster)'s Blog

Tag Archives: error

No documentation – a coding error?

01 Friday Dec 2017

Posted by mp3monster in development, General, Oracle

≈ Leave a comment

Tags

coding, development, docs, documentation, error, NoBugsProject

Documentation

from http://geek-and-poke.com

I came across this tweet from Oracle Developers (Oracle Developers Tweet) which picked up on a post from the NoBugsProject about common errors with the use of exceptions. One of the first errors the article described is one of my pet hates – the use of standard exceptions for application specific errors.

This took me onto one of my other pet hates – code without any documentation. I’m not advocating the days of waterfall Development where reams of documentation had to be produced before a single line of Code was written. In fact this is in my option worse than nothing as the docs would often not match the coded reality. But I absolutely agree with the agile manifesto statement:

We value working code over documentation

This doesn’t say no documentation, despite the fact that I have encountered more times than I care to recall the use of this statement to justify not documenting code. So what is the right balance?

We want to save effort from Code reviews and get clean code by using static code analysis but it doesn’t have the ability to apply smarts as what needs documenting? Pair programming is rarely practised, and there is plenty of psychology about group behaviour that can undermine documentation in a pair working approach effort. So what is the answer?

Well, I’ve always applied a couple of personal rules of thumb that can be measured with static code analysis particularly if you use conventional documentation tags. The rules are:

  • Interfaces warrant an interface level description of the interface purpose. It’s always helpful to describe/illustrate with use example. This is code equivalent to a good API Blueprint or swagger doc.
  • Provide a class level description of what the class is for – if it is a DAO then just say what the entity is.
  • If a class is part of a pattern, name the pattern. This is most important when relating to supporting a composite or solution pattern. Remember there will always situations where a newbie will get asked to extend or change your code, help them. Remember not every developer is as experienced or clever as you. If in doubt, give your code to someone who doesn’t know what you’re working on and ask them to explain what your code is doing and why. I had once, had to create a JDBC abstraction layer as we needed to support multiple databases. But if you know JDBC you’ll be aware of there are some subtle but important differences in implementation of connectors. I took the time to explain it in the interface header. I know a couple of developers appreciated the investment of 5 minutes.
  • If you have a function that has a code analytics score such as cyclometeric then describe the function. Use the comment to convey why the high score is justifiable.
  • If the code has specific dependencies or has to perform in a very specific sequence a short comment will help, and anyone going through refactoring code.

With these guidelines it becomes possible to then use javadoc tools to generate your documentation. It doesn’t require you to go find a word document or a wiki page to update the documentation. Of course then reviewing the generated documentation will soon help you finesse the process of documenting in a manner that is whilst light also supports readability without needing the code.

For those, who still disagree I would say …

  • Do you want to be maintaining and updating the same code for the rest of your career to meet new minor changes etc?
  • Not everyone is a great coder like you, do you want someone less capable who may have to make a change messing up your elegant code?
  • Sooner or later someone will ask you to fix or enhance some code that in your eyes is a chaotic unintelligible mess, I’m sure you’d appreciate some comments that will help you understand what the developer was trying to do? We can’t expect those not so good at the craft to document if the best of us are not prepared to do so.

If you don’t agree, or have found different approaches that ensure enough accurate documentation, please share.

Learning Ansible Review Part 3

08 Sunday Mar 2015

Posted by mp3monster in Book Reviews, Books, Packt, Technology

≈ 1 Comment

Tags

Ansible, book, ebook, error, learning, Packt, publishing, python, reporting, review, rollback

Chapters 4 & 5 of Packt’s Learning Ansible continue to build out strategies needed for enterprise class deployment and configuration management, for example error handling, rollback and reporting in chapter 4.  As chapter, the amount of new Ansible capabilities being introduced is not as substantive as prior chapters, and emphasis is more only what could be described as best practise. For example creating Playbooks that have the means to be invoked to re-establish a prior state if the the execution of the current playbook was to throw up an error.  The callback explanation does need a bit more understanding of how Python works as implementing a callback involves a little bit of Python coding, but the points into which you can hook actions is very rich.

From knowing how to trap callbacks it becomes possible to initiate notifications when events occur in playbooks which is where this chapter moves onto with monitoring and alerting. This really focuses on has my playbook executed as expected and reporting back through means such as email, nagios and graphite.  The examples with email and nagios miss a trick, although the text says you can incorporate output from tasks – it isn’t illustrated; yet if something falters you’d want to see the task output.

Chapter 5 goes into how you might write your own custom modules and test them. Ansible will support any language that is available in your target environment, although Python is the recommended language given its general availability and is the language used to write Ansible, and Ansible modules can be leveraged to shorten the effort in creating custom modules. The chapter then walks through examples using Python, Bash shell scripting and Ruby. A lot of the work appears to be centred on extracting the appropriate parameters to allow the module to run with. The final part of the chapter looks at testing with the Python Nose library.

Solid chapters, and perhaps a little shorter than the first few, but importantly continuing to be well written although perhaps a couple of small missed opportunities to be great chapters.

Prior chapter reviews:

  • Learning Ansible Part 2
  • Learning Ansible Part 1

 

Oracle Ace Director

Oracle Ace Director

TOGAF 9

Unified Logging with Fluentd

Oracle Cloud Integration Book

API Platform Book

Oracle Dev Meetup London

Categories

  • App Ideas
  • Books
    • Book Reviews
    • Oracle Press
    • Packt
  • Enterprise architecture
  • General
    • economy
    • LinkedIn
    • Website
  • Music
    • Music Resources
    • Music Reviews
  • Photography
  • Technology
    • APIs & microservices
    • chatbots
    • Cloud
    • Dev Meetup
    • development
    • drone
    • FluentD
    • mindmap
    • OMESA
    • Oracle
      • API Platform CS
        • tools
      • Helidon
      • ITSO & OEAF
      • Java Cloud
      • NodeJS Cloud
      • OIC – ICS
    • TOGAF
    • UKOUG
  • xxRetired

Twitter

  • Adventures in DevOps –@Fluentd blog.mp3monster.org/2021/01/20/adv…Next Tweet: 2 days ago
  • A nicely explained article about why security needs to start with people. lnkd.in/dwHpT-rNext Tweet: 3 days ago
  • I love stories like this, how physical music has helped them reconnect. How My Record Player Helped Me Feel the Mus… twitter.com/i/web/status/1…Next Tweet: 1 week ago
  • Xmas break has been for trying to finish putting the house together, today finally got my main hifi @Cyrus_Audio am… twitter.com/i/web/status/1…Next Tweet: 3 weeks ago
  • Chapter 7 and Appendix D of Unified Logging with #Fluentd is available as MEAP @ManningBooks - covering performance… twitter.com/i/web/status/1…Next Tweet: 3 weeks ago
Follow @mp3monster

OraWorld

OraWorld

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 570 other followers

Blogs I Follow

  • Rick's blog
  • A journey in development
  • Phil (aka MP3Monster)'s Blog
  • RedThunder.Blog
  • A millennial's musings
  • Shalindra's Blogs
  • BTplusMore
  • Creativenauts
  • PaaS Community Blog
  • RedStack
  • Musings of an Enterprise Software Technologist
  • The Open Group Blog
  • SutoCom Solutions
  • Rob's Wall Of Music
  • DataCentricSec.com
  • A World of Events

My Other Web Content & Contributions

  • All My Links
  • Amazon Author entry
  • API Platform
  • Dev Meetup (co-managed)
  • Fluentd Book
  • http://phil-wilkins.uk/
  • ICS Book Website
  • Mindmaps
  • Monster's Photos
  • my Capgemini Profile
  • OMESA
  • Oracle Community Directory
  • Packt Author Bio

RSS

RSS Feed RSS - Posts

RSS Feed RSS - Comments

Calendar

January 2021
M T W T F S S
 123
45678910
11121314151617
18192021222324
25262728293031
« Dec    

Other Pages

  • About
    • Presenting Activities
  • Books & Publications
    • API Platform
      • API Useful Resources
      • Useful Reading Sources
    • Fluentd, Unified Logging With
    • Oracle Integration
  • Mindmaps Index
    • Patterns Sources

Goodreads

Flickr Pics

UKOUG volunteersBrightonBrightonBrighton
More Photos

History

OraNA

Aggregated by OraNA

Blogroll

  • A Journey in Development
  • A Neate Blog
  • Blog by Robert van Mölken (co-author on ICS book)
  • Exigency In Specie
  • Ora World
  • SOA4U

Social

  • View @mp3monster’s profile on Twitter
Follow Phil (aka MP3Monster)'s Blog on WordPress.com

Tags

6 Music Aaron Woody Ace AIA album Ansible API apiary API Platform applications article BBC Big Data blog book books Capgemini cd CEP Cloud code concert conference data Design developer development download ebook enterprise FluentD free fusion Good Morning Nantwich Groovy Helidon integration java JBoss jBPM London Luis Weir meetup Microservices mindmap monitoring Music OIC OIC - ICS OOW Oracle Oracle Press OTN PaaS Packt Packt Publishing Patterns Phill Jupitus playlist podcast Presentation promotion Puppet reading Redhat review Security SeeWhy SOA SOA Suite software Technology TOGAF UKOUG video

Blog at WordPress.com.

Rick's blog

End-to-End OIC to SAP integration

A journey in development

A blog-post by blog-post journey of a ERP Cloud Solutions Degree Apprentice

Phil (aka MP3Monster)'s Blog

from Technology to Music

RedThunder.Blog

Demystifying cloud technologies...

A millennial's musings

Shalindra's Blogs

Technofunctional Blogs

BTplusMore

Business, Technology and more

Creativenauts

Personal, design, inspiration, interests.

PaaS Community Blog

by Jürgen Kress

RedStack

Oracle Cloud Stuff

Musings of an Enterprise Software Technologist

My thoughts on Enterprise Software Technologies...and more.

The Open Group Blog

Achieving business objectives through technology standards

SutoCom Solutions

Success & Satisfaction with the Cloud

Rob's Wall Of Music

Thoughts of a lifelong music hoarder...

DataCentricSec.com

A World of Events

A Blog for Event and Data Analytics

Cancel
Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Our Cookie Policy