Chase Smith

@ninjattic

I'm working on a beginner-friendly reference site that's all about coding. Here, I'll mainly write about the progress I'm making on my site, as well as behind-the-scenes views on new posts.

1,960 words

https://thinkingincode.ninja @ninjattic Guestbook
You'll only receive email when Chase Smith publishes a new post

Behind the screen -- new post: Program modeling

I had some pretty bad writer's block since I made my last post on Listed where I detailed what I would write about next. I realized that there was something I needed to write about before I could really write about any of those topics, but it took me several days to figure out what it was. I wanted to write about one of the topics I had put down for the "fundamental concepts" series, but, except for the one on Documentation, I couldn't just write about them, I needed some kind of post before that laid the foundation for why they're worth writing and reading about.

After a few days of thinking, I started putting together some thoughts to try to get started on a post. I got it partially written, but I realized it still wasn't what I wanted. Something finally clicked though, and I figured out what I needed to write about: program modeling.

The reason why program modeling is the topic I had to write about next is that if I want to write about things like files or linked lists, I have to somehow convey the idea that I'm writing about these topics so that others can connect the dots and see how everything ties together. I personally am a very visual person, and I see code and systems as being connected, and I link every new thing I encounter to things I already know; this, coupled with the fact that I am the one building my site and know the messages I'm trying to convey, means that I will of course see each post I write in the way I intended, that everything builds off of prior material (with the exception of my first few posts, which I wrote before I had a good idea of where I was going with the site). I can't assume that everyone else who reads my site will know that I'm intentionally building it up in this fashion. By creating a post that goes over different ways of building representations and models of systems and programs, and which stresses the importance of understanding the fundamental concepts, I feel I can now write about those concepts without issue.

Now that all of that is out of the way, let's get on to what I wrote about.

When trying to figure out how a program works, you usually build a model of it internally in your head in a way that makes sense to you and you alone. That being said, there are ways to model programs externally (ie in ways that can be easily shared with others). Knowing some of the ways that programs can be modeled, as well as some of the approaches to actually creating a model, is thus the topic of this new post.

I wrote about three representations of systems and programs:

  • Flowcharts (or process flows)
  • Written text (sentences or paragraphs)
  • Pseudocode

Flowcharts are obviously the most visual representation of a system. Their chief advantage is that they highlight application logic, and easily hide implementation details with a few words at each step. They're well-suited for describing systems with complex logic, or where the logic is at least as important as the actual steps being performed.

Written text is easily understandable by everyone, and its largest advantage is that it's easy to go into as much detail as needed, skipping over implementation details when they would otherwise bog things down, or going into great detail when describing complex components. There's never really a reason to not have a written representation of a system.

Pseudocode is best used when conveying intricate details of an algorithm in an easy-to-reproduce manner. You wouldn't generally want to write a pseudocode version of an entire program, and pseudocode on its own is not enough, there needs to be at least a brief explanation of what is going on. However, when used correctly, pseudocode can greatly enhance documentation.

I wrote about the following approaches to modeling:

  • Bottom-up modeling
  • Top-down modeling
  • Meeting in the middle

Bottom-up modeling consists of starting with the basics and building new components up from existing components, implementing application-specific logic only when all application-specific components are built. It's great for testing as you go, because at all stages you'll have a complete program (at no point should there be any undefined functions or objects). It's not so great though if you're wanting to quickly get the shell of a program done, because that takes a while to form with a bottom-up approach. It also can be overwhelming at times, since you're starting with the "implementation details" instead of hand-waving them until later.

Top-down modeling is the opposite, starting with application-specific logic and, as I said, hand-waving the implementation details until farther down the line (generally the last thing done, actually). It's a great approach for getting a good idea of what the system is and how it will function, but at the same time, because the final implementation details are put off until last, it's possible that the realities of implementing the system make the design infeasible.

"Meeting in the middle" is an approach that combines the previous two: as application-specific components are designed and created, low-level implementation-specific components are also created; application functionality is built "down" while supporting pieces are built "up". The application is thus designed and developed a component at a time, where each component is fully functioning and in its final form once it's created. The main drawback of this approach is that you essentially need to have the whole thing planned out from the start, since it's hard to build something a component at a time if you don't know what those components are and how they'll relate to each other.

You can read the post in its entirety here: https://thinkingincode.ninja/posts/program-modeling

Thanks for reading!

What I'll write about next

There are so many things that I'm going to write about on my site, so many topics I want to cover. I realize that I can't write about them all at once, I have to focus on one topic at a time, so that content quality doesn't suffer. At the same time, however, I also can't write about these topics in whatever order I feel like, there has to be some kind of order to them. My goal is to make a beginner-friendly site, so that means I can't start with the more complicated things like pointers and references, or cache optimization, or how to successfully refactor code, without first covering things like memory and how CPUs really work, or how to recognize duplicate code patterns. Basically, I can't start with the stuff that I had originally brainstormed as topics to write about, because doing so would make it harder for beginners and novices to understand what I'm writing about.

Now, even though I keep saying 'beginner-friendly', that doesn't mean I'm writing tutorials on how to program in particular languages or that I will avoid technical subjects, far from it. I just think that it makes sense to start with the basics and get them covered, so that I can build on them to cover increasingly advanced topics, without worrying nearly as much about only a certain portion of my readers understanding the topic.

So, all that being said... What's my plan to get started?
Roughly, this:

  • Write several more posts in the "Fundamental concepts" series, including, but not limited to:
    • Files, folders, filesystems
    • The terminal
    • Input/output
    • Error detection, handling
    • Program parameters
    • Documentation
    • Linked lists
    • Binary trees
    • Hash maps/dictionaries
  • Write some more posts in the "Effective coding" series:
    • How to comment effectively
    • How to name things well
    • Picking a good order for function parameters
    • The importance of lining code up
    • How code should generally be structured to maximize readability
  • Some posts on "Understanding and refactoring code":
    • Recognizing code patterns
    • Pulling out intent from code
    • How to remove global variables

I have (lots) more topics I haven't listed, but I think that that's a pretty good start. I think that's enough to last me at least a month, if not two. But once I've written about these things (especially the "Fundamental concepts" topics), it'll greatly widen the range of topics that I can write about without worrying that a beginner (who has read through the "Fundamental concepts" posts) will be lost.

Right now I don't really have a written list of all of the topics I'm going to write about. Once I get those posts done, I will start putting such a list together (and publish it on my site). If you have any ideas, let me know, I'm open to suggestions!

I'm going to make my blog generator open source

In the process of creating my site (https://thinkingincode.ninja/) I basically ended up creating a program that could be used to generate a blog site (though my site is not a blog). I lay out my motivations for doing so, and an overview of the folder and file structures it works with here (https://thinkingincode.ninja/posts/how-this-site-is-built), though it's slightly outdated as I rewrote the site generator since that post was published (I'll update that post after the generator is open-sourced, because there might be more changes in the process of making it open source).

My decision to make the generator open source came because I wanted to possibly use the generator to create a separate site for more traditional blogging purposes. Doing this though would mean de-coupling the code for the generator from the repository for my site, so I figured, at that point, I might as well open the generator up for the world to see and use.

The name of it is Spark, because it's a static blog generator.
Key features:

  • Site content is defined using folders and files (the first iteration of the generator was a series of shell scripts, so having separate files for things like the title or description worked quite well)
  • Pages and posts are written in HTML, and can contain arbitrary HTML
  • Pages are wrapped up in a header and footer that give the entire site a uniform appearance
  • Generates an RSS feed file
  • Posts can be hidden until after a specific publish date/time
  • CSS is added in a <style> element, not linked to as a separate file (for my purposes, I wanted a site where there are no dependencies on any external files after the initial HTML file is loaded)
  • Posts marked as having code will have CSS be added for syntax highlighted <span>'s (note, the <span>'s are not calculated, you have to manually write them out in the post HTML file)
  • Generates two versions of the site, one with a dark theme, one with a light theme; all generated pages contain links to the alternate theme page
  • Output files won't be written if they wouldn't be changed
  • Fairly unopinionated about the appearance and structure of the site it generates
  • Extremely fast

It's written in C, and presently the only dependency it has is on the date program, because parsing times and timezones in C, using just the standard library, measures somewhere on the difficulty scale between "nightmare" and "straight up impossible".

Check out my site to see what it looks like in action!

I'm going to try to finish getting it open-source-ready over the next few days, but I can't guarantee anything. It'll be happening soon though. Once I've made it open source, I'll update this post with a link to the GitHub repository, and I'll also be publishing a fairly lengthy post on my site about it.

Update 10:25PM CDT 6/4/2018: It's officially publicly available!
Announcement post: https://thinkingincode.ninja/posts/announcing-spark
Demo site: https://spark.thinkingincode.ninja
GitHub repository: https://github.com/chase-smith/spark