Code Something Weekly: How and Why
Introducing C.S. Weekly — A Manifesto
When it comes to the world of hobby software projects and building a tech showcase, I have a big problem. I think big. Too big.
Elephant projects.
End-to-end.
If it can’t compete with products built by companies employing teams of developers on a 6+ figure budget, it’s not good enough. Surely one college student with their head in the clouds ought to keep up.
Except I’m not Harlan Mills, and it’s likely the case that you aren’t either.
v0.0.99-alpha.10.3
My Github account is full of ambitious projects sitting at early stage development. It’s both beautiful and shameful. The code is usually well documented and the features of Github are being used to their potential — but how do I show others my capabilities, when all I have is complicated monorepos?
Others aren’t cloning my development environment, setting up special databases, complicated configurations and API access keys just to see my unfinished work.
Sure there’s Heroku and Github hosting, but it just feels too raw and unfinished to launch.
Just a few more features.
Tweak the style a bit.
Almost there.
If you’re anything like me, you get perhaps too much of a thrill when spinning up a new project.
You love requirements engineering.
You love crafting an architecture.
You love modular decomposition.
You love creating diagrams and documentation.
You love creating a new dev environment.
You love writing the first set of unit tests.
You love the first real pull request.
In essence, you love problem solving. You’re philosophical and focused heavily on higher-order concepts in the external world.
But with some honest self-reflection, you know you don’t prioritize the minutiae of task scheduling and micro-management.
In other words, once a project gets going, it starts to get a little more monotonous. And there are always sticking points. Always.
The 3 Project Types
If you think back to that requirements engineering 101 lecture you skipped, there are roughly three types of projects in the world of requirements engineering:
- Rabbit
- Horse
- Elephant
Keep in mind, these don’t necessarily have to do with the project size or code-base. Rather, the size is relative to the requirements process.
I’ll outline the key differences.
Rabbit Projects
Rabbit projects are considered suitable for agile development in smaller teams. Frequent requirements and development iterations can be used. Think of a very simple web application — most are launched as soon as the developer(s) have a core set of features. The remaining features are slowly rolled out in an ongoing manner. Changes can be made rapidly and readily.
Many features aren’t even fully elicited until after the initial version is launched by analyzing how the user base engages with the product.
Github issues, internal Slack channels or even a shared office whiteboard can be used to plan the next iteration cycle.
It’s noteworthy that the features can even be implemented in such an incremental way. Imagine using this process for control system software in a nuclear power plant. If all that happens is a todo log when the pressure from subsystem C raises above threshold, we’ve got meltdown. Literally.
Horse Projects
The major difference between Horse projects and Rabbit projects is a need for a requirements team and documentation. Most corporate environments have multiple divisions beyond a team of developers. There’s a need for internal communication between the divisions as well as the input of multiple stakeholders. Thus, the development team usually has a dedicated project manager or management team that will in some way document and orchestrate the developers with assignments.
Note that the aforementioned document isn’t software documentation. Regardless of a project’s size, there should always be software documentation or at least a README. Rather, requirements documentation attempts to organize information such as project constraints, deadlines, stakeholder input, storyboards, high-level functions and many non-functional aspects such as how a product looks, behaves and provides maintenance support.
For an opinionated version of a requirements document suitable for corporate environments, here are two well known templates:
Elephant Projects
Elephant projects require the work of professional requirements engineers. These systems are either large, complicated, safety-critical or all of the above and more.
Beyond just gathering and eliciting a complicated set of requirements, there’s often a necessity to prove a system design at the requirement phase in an elephant project. In the running example of the nuclear controller, it would be handy to know exact voltages and number of signals before designing controller hardware. It’s also necessary to prove that any concurrent operations won’t cause system deadlock. Otherwise, you’re going to have to start again or cause a meltdown. And please, no more meltdowns.
Beyond the system design, the product being created is usually meant to be built to last. In other words, if the nuclear power plant system controller is so poorly designed that it needs to be constantly patched and updated, we’re probably in for some bad news. Instead, the product is meant to be built once, correctly.
A refresher on the project types primarily serves as a reminder that the main difference between software projects are factors related to requirements: team size, scope and what features needed to be included for any given launch.
Factors such as complexity of code, conceptual difficulty, platform and application type aren’t necessarily what determines a project effort in the long term.
Managing Hobby Projects
For the purpose of hobby efforts, let’s keep the semantics of the three projects the same but modify them to suit the needs of the student or underemployed (read junior) developer: small or no team, limited time, tooling and no budget.
Rabbit Projects
- A singular feature or a set of cohesive functions
- requirements analysis is unnecessary
- If the project is to evolve over time, it is mainly to fix bugs/typos, update dependencies and other similar patches.
- The projected time to complete the initial project is within the range of 1–14 days
Horse Projects
- A set of Rabbit features
- A minimal design (wireframing, etc) or requirements analysis is useful or needed
- The set of features could be hacked concurrently by some of your pals in a Github repository
- The projected time to complete the project is in the range of 30–90 days
Elephant Projects
- There are conceivable iterations that the project could undergo from its inception (multiple major/minor versions)
- Analysis and design phases are needed
- Can handle 1 or 2 of such projects a year
- Although they may not be “built to last”, a stable API is to be developed
These project definitions imply the following approximate yearly schedule:
- ~1 main focus or new elephant project per year. Maintenance of a previous effort.
- ~4 horse projects per year
- ~2–4 rabbit projects per month
Most of us are perpetually engaged in horse or elephant projects. But given this schedule, we’d engage in an approximate 24–48 rabbit projects a year!
In time, a few of these rabbit projects can be put together as a showcase of your skill set. Rather than trying to perfect the one app that demonstrates it all, be able to demonstrate your ability to problem solve in many ways.
Given the sheer volume of rabbit projects, it’s worth exploring them further.
Code Something Weekly: Manifesto
As a student, novice or not-yet employed developer, weekly projects have much more to offer than large elephant projects. However in order to realize their utility, we must approach them correctly.
Thus I present the Code Something Weekly Manifesto:
Explore. Relax. Code. Write.
Explore
Each week will bring forth an opportunity to learn something new, explore, tinker, prototype and ultimately have fun. A weekly rabbit project is time for you to grow as a developer. It’s like hitting the gym or cooling down with a session of yoga.
Was there a topic you covered in school that you enjoyed— even in an area unrelated to computer science?
Do you follow anyone on YouTube or written tutorials such as Hacker News?
Have you ever done a programming challenge or code golf?
This is the time to explore.
Relax
Stop worrying about code review and refactors.
Stop scope creep and worrying about product launch.
Stop figuring out how to write that tricky integration test.
Breathe.
Have coffee, tea or a brew and just hang out.
Do something new and completely different.
Remember that you love coding and problem solving.
Code
In this scenario, there are no wrong moves. Some of the code will be less than perfect or slightly sketchy. That’s ok — nothing is ever perfect at first. The only wrong thing you can do is break the rules of a rabbit project. Keep things to a few functions or a single feature.
Here are a few ideas
- implement a mathematical concept you learned in university or college
- remake all or part of TODO MVC or a similar toy feature in a new language or framework
- practice some algorithms — re-write them in your own utility class or with your own data structure
- do an adobe photoshop, illustrator or other vendor asset creation tutorial (step outside code, but within a related domain)
- find something on MDN docs that you don’t know and use it in an exercise
- re-implement a function, class or module from an open source project you follow
- (re)read a chapter of a book (and do 1 or 2 of the exercises). This repository contains free PDFs
- build a simple CLI to handle a common task
Essentially, pretend you’re doing an exercise or assignment from a college course.
Write
When you’re done, post it on Github, Codepen or a similar service. Write about it, even if it’s a simple yet properly written README. Make a blog post or article. For those that are shy with their words, a diary or unpublished post is just as good.
The point is not to tell others how great you are or compose a perfect tutorial. Rather, the ability to recap and explain something is integral to learning (see Feynman Technique).
It’s also desirable to have the ability to look back on everything you’ve learned in a given period of time and make better sense of it all.
My hope is that you’ll find time throughout your week to be at peace with code. It can be one dedicated day, the entire weekend or maybe scattered patches throughout the week during breaks from other work. It’s less about an exact structure and more about creativity, learning and fun.
Happy coding :)
