Documentation and Commenting Your Code for Open Source Projects #piday #raspberrypi @Raspberry_Pi

Pasted Image 1 5 15 1 41 PM

Here’s an excellent piece by Alex from RasPi.TV, sharing a number of different approaches, opinions, and suggestions for how to document your code — a crucial aspect of participating in open source software and the Raspberry Pi movement!

Well worth reading, finding gems, arguing your case — this is important stuff.

…From observation of the computer industry going back to 1987, when I did a pre-university year at IBM Scientific Centre in Winchester, it seems that the very brightest and best programmers (software creatives) are often not very good at or not very keen on documenting their work.

I think the reason for this is often misunderstood. Poor documentation is a source of great consternation in the world of Linux. In fact it’s a large part of the raison d’être for RasPi.TV. We, the users, often feel that the geniuses who write awesome software can’t be bothered to write good instructions for it because…

  • it’s beneath them
  • they’re lazy
  • they think “it’s obvious how it works unless you’re a retard”

…and, in some cases, there may be some truth in some of those statements. But I suppose the real reason is different. They find creating and writing great software quite a stimulating and fun mental challenge. But, for them, writing instructions is totally boring. And since, when we have a choice, we all naturally shy away from doing things that we don’t enjoy, a lot of Free and Open Source Software (FOSS) remains…

  • undocumented
  • badly documented, or
  • incompletely documented (or permanently out of date docs)

I think it’s the nature of the beast. Free software is free because someone enjoys writing it. But once you’ve sweated long hours over debugging your code and it finally works just as it should, you feel like it’s finished. At that point, the thought of going through it all to show people how to use it may well seem quite repellent. “I’ll have a rest and do it next week.” You think to yourself. But next week a new and interesting programming challenge comes along and the documentation gets swept under the carpet and forgotten about…..

Read more.

Pasted Image 1 5 15 1 41 PM


998Each Friday is PiDay here at Adafruit! Be sure to check out our posts, tutorials and new Raspberry Pi related products. Adafruit has the largest and best selection of Raspberry Pi accessories and all the code & tutorials to get you up and running in no time!


Adafruit publishes a wide range of writing and video content, including interviews and reporting on the maker market and the wider technology world. Our standards page is intended as a guide to best practices that Adafruit uses, as well as an outline of the ethical standards Adafruit aspires to. While Adafruit is not an independent journalistic institution, Adafruit strives to be a fair, informative, and positive voice within the community – check it out here: adafruit.com/editorialstandards

Join Adafruit on Mastodon

Adafruit is on Mastodon, join in! adafruit.com/mastodon

Stop breadboarding and soldering – start making immediately! Adafruit’s Circuit Playground is jam-packed with LEDs, sensors, buttons, alligator clip pads and more. Build projects with Circuit Playground in a few minutes with the drag-and-drop MakeCode programming site, learn computer science using the CS Discoveries class on code.org, jump into CircuitPython to learn Python and hardware together, TinyGO, or even use the Arduino IDE. Circuit Playground Express is the newest and best Circuit Playground board, with support for CircuitPython, MakeCode, and Arduino. It has a powerful processor, 10 NeoPixels, mini speaker, InfraRed receive and transmit, two buttons, a switch, 14 alligator clip pads, and lots of sensors: capacitive touch, IR proximity, temperature, light, motion and sound. A whole wide world of electronics and coding is waiting for you, and it fits in the palm of your hand.

Have an amazing project to share? The Electronics Show and Tell is every Wednesday at 7pm ET! To join, head over to YouTube and check out the show’s live chat – we’ll post the link there.

Join us every Wednesday night at 8pm ET for Ask an Engineer!

Join over 36,000+ makers on Adafruit’s Discord channels and be part of the community! http://adafru.it/discord

CircuitPython – The easiest way to program microcontrollers – CircuitPython.org


Maker Business — “Packaging” chips in the US

Wearables — Enclosures help fight body humidity in costumes

Electronics — Transformers: More than meets the eye!

Python for Microcontrollers — Python on Microcontrollers Newsletter: Silicon Labs introduces CircuitPython support, and more! #CircuitPython #Python #micropython @ThePSF @Raspberry_Pi

Adafruit IoT Monthly — Guardian Robot, Weather-wise Umbrella Stand, and more!

Microsoft MakeCode — MakeCode Thank You!

EYE on NPI — Maxim’s Himalaya uSLIC Step-Down Power Module #EyeOnNPI @maximintegrated @digikey

New Products – Adafruit Industries – Makers, hackers, artists, designers and engineers! — #NewProds 7/19/23 Feat. Adafruit Matrix Portal S3 CircuitPython Powered Internet Display!

Get the only spam-free daily newsletter about wearables, running a "maker business", electronic tips and more! Subscribe at AdafruitDaily.com !



No Comments

No comments yet.

Sorry, the comment form is closed at this time.