Vault/books/code_complete.md

Part 1

Chapter 1

What is Software Construction?

Software development is akin to a construction project, the real process of construction includes some aspects of planning, designing and checking your work. Software development is not just about coding, there are many other processes and activities involved. Using Construction as a metaphor to software development is fairly accurate, but needs context to differ which activity is construction, and which isn't

• Problem Definition : Not Construction
• Requirements Development : 10% Construction
• Construction Planning : 90% Construction
• Software Architecture, or High-Level Design : 20% Construction
• Detailed Design : 75% Construction
• Coding and Debugging : 100% Construction
• Unit Testing : 95% Construction
• Integration : 80% Construction
• System Testing : 20% Construction
• Integration Testing : 90% Construction
• Corrective Maintenance : 10% Construction

As the list above shows, Construction is mainly Coding and Debugging, but also involves detailed design, construction planning, unit testing, integration, integration testing, and others. This book focus on construction, and will use coding and programming interchangably with the word construction. In descending order of focus:

• Coding and Debugging

• Detailed Design

• Unit Testing

• Construction Planning

• Integration

• Integration Testing

• Software Architecture

• Problem Definition

• Requirements Development

• Correction Maintenance

• System Testing

The brief high-level overview of what is involved in a construction process is as follows:

• Verifying that the groundwork has been laid so that construction can proceed successfully
• Determining how your code will be tested
• Designing and writing classes and routines
• Creating and naming variables and named constants
• Selecting control structures and named constants
• Unit testing, integration testing, and debugging your own code
• Reviewing other team members low-level designs and code and having them review yours
• Polishing code by carefully formatting and commenting it
• Integration software components that were created seperately
• Tuning code to make it faster and use fewer resources

Brief overview on non-construction activities on a high-level are as follows:

• Management
• Requirements Development
• Software Architecture
• User-Interface Design
• System Testing
• Maintenance

Non-Construction activities plays an equal role to the success of a project as Construction activities

Why is Software Construction Important?

The question is more of why the emphasized importance of the construction process an important focus:

• Construction is a large part of software development, from 30 to 80 percent of the total time spent on the project
• Construction is the central activity in software development, it allocated at the center of the timeframe for a project
• With a focus on construction, the individual programmer's productivity can improve enormously, understanding these processes, helps the programmer
• Construction's product, the source code, is often the only accurate description of the software, documentations, requirements specification, design documents, can be outdated. Therefore ensuring the source code is in the highest of quality is important
• Construction is the only activity that's guaranteed to be done, real world projects tend to bbe imperfect, testing might not be done, requirements might be skipped, but construction will always be finished, or the project ceases to exist

How to READ (this book)

If you like to read cover to cover go with chapter 2

If you want to get programming tips go to Chapter 6 and cross reference

If you don't know go to Section 3.2 "Determine the kind of Softeare You're Working On."

Key Points for Chapter 1

• Software construction is the central activity in software development; construction is the only activity that's guaranteed to happen on every project
• The main activities in construction are detailed design, coding, debugging, intergration, and developer testing (unit-testing and integration testing)
• Other common terms for construction are "coding" and "programming"
• The quality of the construction substantially affects the quality of the software
• In the final analysis, your understanding of how to do construction determines how good a programmer you are, and that's the subject of the rest of the book

Chapter 2

The Importance of Metaphors

Important developments arise out of analogies, the use of metaphors to comparing development problems to something familiar is called modelling

Many scientific developments are done by comparing things scientists were witnessing or things they are familiar with, to produce scientific breakthroughs

Models, are powerful because they are able to provide properties, relationships, and additional areas of inquiries, to something that is unfamiliar.

It is important to make sure that the model is not overextended, leading to areas of inquiries that are misleading

A good metaphor is simple, relate well to other relevant metaphors, and explains much of the observation

A single problem might have multiple possible models, each models having different views, and have the person ask different questions, and possibly failing or succeeding in fully understanding the ground truth

When a breakthrough in development is achieved, after some time, the model used for the breakthrough has expired, The breakthrough became common sense, and the outdated model becomes something that is impossible to envision

There is no switch from the wrong metaphor to the right one, it is a progressive change from a worse metaphor to a better metaphor

Just because there is a newer model, does not mean the older model is useless. Engineers still use newtonian dynamics even when its been supplanted by einsteinian theory

Software Development is still a young field, and has no set of standard metaphors. Many metaphors used now can be better or worse, conflicting or complementary

How to Use Software Metaphors

An algorithm is a set of well-defined instructions. Predictable, deterministic, not subject to chance.

A heuristic is a technique to help you look for the answer. It is subject to chance, tells you how to look, a type of algorithm that is not deterministic

A software metaphor is a heuristic, not an algorithm. The hardest programming problem is conceptualization, therefore there is no predictable, deterministic way to solve the problem

A software metaphor cannot provide instructions to how to solve the problem, or all programming problems, there is no metaphor possible to model out a general instruction to fixing all programming problems

A software metaphor therefore is a heuristic because the model for the metaphor can help you on where you should look for the answer, not how to solve the problem

Use a software metaphor to create insight into your programming problems and process, With time and practice on developing better and better modelling for the codebase, their development and code quality will be better than those who don't use them.

Common Software Metaphors

• Software Penmanship: Writing Code
  • Writing code is just like writing a letter:
    • Just write it start to finish, no plan, figure out as you write along
    • Sit by the fire with a glass of brandy, a good cigar, and being able to enjoy a literate program
  • When the writing is finished, it is deployed, no more changes, and considered complete
  • It works for a small scale project, or individual work, but not suitable for anything else. Writing is usually a one-person activity
  • In writing, originality is more important, but in software development, focus is on reusing design ideas, code, and test cases, from battle tested projects
  • This metaphor is too simple and too rigid, popular books perpetuate this and states the following:
    • Plan to throw one away; you will, anyhow.
    • If you plan to throw one away, you will throw away two
  • Throwing things away is not optimal for software development, as the cost of development is too high to simply restart the whole process again
• Software Farming: Growing a System
  • Writing code is like planting seeds and growing crops:
    • you plant the seeds, writing a piece of function, test the function, and again and again
    • small incremental steps, minimize trouble, and add it to the System
  • this metaphor is too vague, besides showing that code progress should be in small incremental steps
  • hard to expand the metaphor, what is fertilizing the system plan, increasing code yields through land management, etc etc
• Software Oyster Farming: System Accretion
  • Writing code is like an oyster producing a pearl
    • Through acretion, having the the development process be repetitive and incremental
    • Creating a skeleton (a grain of sand) of the codebase, slowly changing dummy code for real ones, adding basic functions then advanced functions
    • its incremental development
  • Its a metaphor that doesn't overpromise, showcases that software development is a slow iterative proccess
  • Inspiration behind the modern agile programming approach
• Software Construction: Building Software
  • Writing code is like construction
    • If its a small project, you can do it in an afternoon, start over if you made a mistake, cheap, and no need for meticulous planning
    • If its a large project, it is the other way around, planning becomes important, design choices impact the development process and outcome. Mistakes become impossible to fix
  • For large construction projects, you need to prepare the building site, hire contractors, draw blueprints, lay foundations, build frames, wire and plumbing, put siding and roofs, then possible additional steps like beautifying gardens, pools, post construction maintenence, etc.
  • Its the same with large software projects
  • A well planned project improves the ability to change your mind later, plan enough so that the lack of planning doesn't create major problems
  • Different softearer projects can benefit from different development approaches, can be loosely planned, meticulously planned, steps to take, etc.
  • Cost of change works in this model as well, depending on the code that requires change, it might range from trivial to impossible, like moving the elevator shaft in a skyscraper
  • This metaphor is the most powerful one-person

Applying Software Techniques: The Intellectual Toolbox

Experienced Programmers learn and accumalate techinques throughout the years, but these techinques are not rules, they are analytical tools. The knowledge to choose the right tools for the job, the right type of modeling to use to solve a problem

Its not about learning the correct methodology, but rather having a toolbox of methodologies to choose from.

Combining Metaphors

Metaphors are heuristics, and not mutually exclusive. You can combine metaphors together that communicates well with others on the team. Just make sure its not overextended.

Key Points

• Metaphors are heuristics, not algotithms. As such they tend to be a little sloppy.
• Metaphors help you understand the software-development process by relating it to other activities you already know about
• Some metaphors are better than others
• Treating software construction as similar to building construction suggests that careful preparation is needed and illuminates the difference between large and small projects
• Thinking of software-development practices as tools in an intellectual toolbox suggests further that every programmer has many tools and no single tool is right for every job. Choosing the right tool for each problem is one key to being an effective programmer.
• Metaphors are not mutualy exclusive. Use the combination of metaphors that works best for you.