How much Time Do you plan before touching the Keyboard?
- Thread starter Shafty
- Start date
Sounds like it doesn't matter how much time anyone else takes to plan. It sounds like YOU need to start planning more and better.
I touch the keyboard while planning.
For programming, I start with a set of requirements for the program. If the program is very trivial so are the requirements but as complexity increases the requirements follow.
The requirements should be abstract and not include any implementation details. You want to know what the program need to do, not how it will do it. That comes later. It is very helpful to craft the requirements around "user stories" or other Use Case Methodology tools.
While UCM can be complex and rigorous, it is very powerful even when employed partially and informally. Key elements are: thinking of the program from the point of view of the user and using the terminology of the user. For example, the program is a database tracking inventory, don't invent a new term for the unique ID of the item. Even if you will eventually create some sort of primary key, if the user currently tracks by serial number, and they call it a "registration number" in your requirements and in the eventual program make sure they can track by serial number and call it that.
In other words, don't make the user work for your program—your job is to do the opposite.
After you have a good idea of what success looks like from the "customer's" point of view, you need to work out the how part. Before you write a single like of code, there are some things you need to document. The primary one is names. The names of variables and functions are very important to a successful, sustainable, and scaleable program.
This is because the names form boundaries for the functions of these things. They tell you, sometimes by analogy, what each does in the program. Always name variables so their function can be understood by the name. For example, don't label something that counts boxes as "counter1" call it "boxCount", etc. And whether you use camelCase or some other convention, stick to it.
As far as functions go, name them so you can tell everything that happens inside them, and don't mix unrelated things into them. If you find yourself duplicating a lot of code, write a separate function for that, don't ever double up the use of a single function, it will inevitably bite you.
By the way, documenting these variables and functions is the first time I will be in the code editor. I document them by declaring them and using comments. In particular in the case of functions, I include a comment block with the following information:
By including this sort of "nanoapi" as part of the structure, you have the great luxury of being able to replace any function without side effects. This is only true if you stick to the one function per function rule. It also leads to exceptionally clean main code, consisting mostly of program flow calling functions with the return values of other functions, and limited "glue" code that doesn't merit a function itself.
This is much easier to read and modify.
There is a book's worth more to say, but I will stop here leaving you with one more related but tangential point. If you don't already do it, use version control as if it was your religion. Learn and use some revision control system (git is almost always the best choice in the current environment, even if there are "better" options).
The amount of trouble you will save yourself if you learn it well and use it carefully will pay back any investment in time and discomfort of learning something a bit arcane. If you get anything out of this screed, let it be that—version control is your friend when everyone else has abandoned you.
For programming, I start with a set of requirements for the program. If the program is very trivial so are the requirements but as complexity increases the requirements follow.
The requirements should be abstract and not include any implementation details. You want to know what the program need to do, not how it will do it. That comes later. It is very helpful to craft the requirements around "user stories" or other Use Case Methodology tools.
While UCM can be complex and rigorous, it is very powerful even when employed partially and informally. Key elements are: thinking of the program from the point of view of the user and using the terminology of the user. For example, the program is a database tracking inventory, don't invent a new term for the unique ID of the item. Even if you will eventually create some sort of primary key, if the user currently tracks by serial number, and they call it a "registration number" in your requirements and in the eventual program make sure they can track by serial number and call it that.
In other words, don't make the user work for your program—your job is to do the opposite.
After you have a good idea of what success looks like from the "customer's" point of view, you need to work out the how part. Before you write a single like of code, there are some things you need to document. The primary one is names. The names of variables and functions are very important to a successful, sustainable, and scaleable program.
This is because the names form boundaries for the functions of these things. They tell you, sometimes by analogy, what each does in the program. Always name variables so their function can be understood by the name. For example, don't label something that counts boxes as "counter1" call it "boxCount", etc. And whether you use camelCase or some other convention, stick to it.
As far as functions go, name them so you can tell everything that happens inside them, and don't mix unrelated things into them. If you find yourself duplicating a lot of code, write a separate function for that, don't ever double up the use of a single function, it will inevitably bite you.
By the way, documenting these variables and functions is the first time I will be in the code editor. I document them by declaring them and using comments. In particular in the case of functions, I include a comment block with the following information:
- What the function expects to get in terms of passed parameters
- What the format of those parameters are
- What the function returns
- Any comment that explains something important that isn't obvious from the from the foregoing or code.
By including this sort of "nanoapi" as part of the structure, you have the great luxury of being able to replace any function without side effects. This is only true if you stick to the one function per function rule. It also leads to exceptionally clean main code, consisting mostly of program flow calling functions with the return values of other functions, and limited "glue" code that doesn't merit a function itself.
This is much easier to read and modify.
There is a book's worth more to say, but I will stop here leaving you with one more related but tangential point. If you don't already do it, use version control as if it was your religion. Learn and use some revision control system (git is almost always the best choice in the current environment, even if there are "better" options).
The amount of trouble you will save yourself if you learn it well and use it carefully will pay back any investment in time and discomfort of learning something a bit arcane. If you get anything out of this screed, let it be that—version control is your friend when everyone else has abandoned you.
Jerry-Hat-Trick
- Joined Aug 31, 2022
- 450
Thirty years ago for a large UK company which shall remain nameless I took over responsibility for turning around a software development project where around a dozen code writers were a year late completing a large contract. I took away their computers and we spent a day mapping out what needed to be done, starting from scratch, on a huge whiteboard. Within a week we had chopped the project into a written list of tasks which could be allocated to one person. Within 6 months, we had a working system. It's comfortable to fall back on all the available sotware tools but an engineer needs to learn to segment problems. If it's just one person writing the code it's possible to leap straight in but if it's a team....
You May Also Like
-
An A-Weighted Analog Filter that Mimics the Response of the Human Ear
-
Apple Announces M3 Family: ‘Most Advanced Chips for a Personal Computer’
by Jake Hertz
-
Researchers Rethink Computer Vision With All-Analog Photoelectronic Chip
by Duane Benson
-
In-Ear Sensors Record Health Metrics From Brain Activity and Sweat
by Jake Hertz
