Jump to content

A general guide to programming


Nihilith

Recommended Posts

This is my point of view, the way I do it. Certainy not the only nor the best way, but mine, and believe me or not, it never betrayed me. These explanations are as language independant as possible, even if I sometimes rely on code to explain some stuff

 

What do I need to start a project :

 

  • a whole pile of blank paper
  • a whole pack of pencils
  • patience
  • time and calm !

did you notice that no computer is involved ?

How do I start a project :

  • Take a sheet of paper, draw an horizontal line in the middle of it
    • in the upper part, write project goals
    • in the lower part, write the needs (any need for a database, a particular library such as image manipulation ?)

Coffee making :
goal : I must make coffee
.
--------------------------
.
needs :
a coffee machine
a filter
water
coffee
.
methods :
fill the machine with water
put coffee in filter
switch on the machine
switch off the machine

 

next revision :

Coffee making :
goal : I must make coffee
.
--------------------------
.
needs :
a coffee machine
a filter
water
coffee
.
methods :
.
fill the machine with water
.
empty the coffee machine bottle (english name for the recipient the coffee goes to, please ?  ) (if not empty)
wash the coffee machine bottle (if not clean)
place the coffee machine bottle (if clean)
.
put coffee in filter (only if filter is in the machine and filter is a new one)
open the filter compartment
remove filter (if filter is not a new one)
place new filter in machine (if old filter not present)
.
switch on the machine (only if everything is ok to proceed)
switch off the machine (when coffee is done)

In this revision, conditions start to appear in the parenthesis...

 

I generally draw a process schema to put everything in the correct order, with forks wheter a condition is satisfied or not. It's called modeling a program.

 

Anyway, stay in the general approach of the project. For example, write down that you need an image library, not that you need this particular image library.

 

  • The others sheets are here to go into further details of the different aspects of the projects
    • Drawing a raw blueprint of the gui (graphical user interface) if any
    • Writing down what inputs the user should need
    • Writing down what you may offer the user to speed up the use of the program (choice list instead of full input etc.)

    [*]if you got support of a database, write the tables description, the fields of the tables, the way they're in relation with each other.

    [*]Never throw the sheets to the bin... instead of it, keep them as revisions (keep them in groups, write down a revision number and a date on the groups). You could then refer to them later to pick up some previous ideas.

    [*]Always use natural language, never use a programming language on these documents.

This paper work can be replaced by a "word" file, but always have some paper next to you, sometimes, ideas pop when you don't expect them. I often use the recorder function of my GSM... Scanning the notes to some files can be a good and portable idea on an USB Key. I always got my 8GB USB key on me, with "portable openoffice" installed on it so I can work my files on any pc even if this pc doesn't have openoffice installed. I also got portable thunderbird and portable firefox on it... but this is another subject.

 

Once the project almost completely written down in natural language, it's time to give the project a new go by choosing the tools.

 

Choosing the tools :

 

Which language ?

 

  • one you're cumfortable with, except if you started this project to give a new language a go

  • one that may make it easy.
    • if the project is web oriented, go for a web oriented language such as PHP, Java or HTML

    • if the project is a game, you may want to go deeper into the control you have on the machine, so C++ could be a good choice.

    • if the project is a simple script, use a simple language such as Python (even if python can handle big projects as well).

    [*]if your project must run on different OS, go for a portable language (avoid Microsoft Visual studio for example)

The good question is : Is it of any use writing a simple ftp back-up tool in 300 lines in C++ if python only needs 30 lines...?

Which IDE (Integrated development environment) ?

 

  • this will depend mostly on the language even if IDE like Eclipse can support many languages.
  • most of programs can be written within the notepad, but an IDE offers more tools to speed up your coding
  • the "look & feel" of the IDE. If you're not cumfortable with it, you won't go far.

some IDE features :

  • Syntax highlighting is really useful, even more with language that are case sensitive. Taking an example in Python and Idle (minimalist IDE), if you type 'TRUE', it will not be highlighted, as the right typo for this constant is 'True' in Python. if correctly typed, it will appear in purple under Idle IDE.
  • Auto code completion : some IDE scans the libraries you're using and most of them offers expression completion. For example, you start typing "gtk.req" and it shows "gtk.require" which is completed by hitting the "Return" key instead of typing it down completely.
  • Embeded compiler : No need to go through complex command lines to get your program running, just a click away.
  • Embeded debuger : shows you the error, the line it's in, and so on.

Graphical User Interface ?

 

  • Go for a GUI Designer, embeded or not in you IDE.
  • It is possible to code the GUI, but prepare to spend a real lot of time for this !

How I setup my project workspace :

 

File Organization

From my point of view, the success of a project is, for a part, in the directory structure of your project.

Here are some of my rules of thumb. And these rules can be applied to other projects such as Photoshop projects or even a "word" project.

  • A folder for each project. Two projects cannot share a same root folder. If you need shared resources for 2 projects, copy paste them between the project folders. Storage isn't an issue nowadays.
  • A sub folder for each type of file. Resources are in a folder, libraries in another, and so on.
  • Sub-sub-folders for sub types. In the resources folder for ex., make a folder for images, source text files, video, sounds and so on.
  • A sub folder for working sheets. Put your word, excel work documents in it.

Don't be too greedy though, and don't get a 10 level deep directory tree... 3 levels is ok

 

Here a simple overview, pretty self explanatory (an image is worth a thousand words)

 

folders.jpg

 

This may be quite confusing at the beginning but believe me, soon, when dealing with big projects, this will prevent from dealing with hundreds of files in a single directory.

 

Some rules :

  • Try to always name the directories the same way from a project to another and in lower case, this way you will avoid a lot of mistakes in the program. (create an empty folder template, and copy/paste it so you don't have to do all the structure again each time you start a project)
  • Instead of typing the whole file path every time, include (c++) or import (python) a file with CONSTANTS which contains the pathes. Example, my constant IMG_PATH contains "res/images/"

IMG_PATH = 'res/images/'

so to load an image, I usually type :

image.load(IMG_PATH+<filename>)

As the resources don't really change along with the versions of your program, the revisions folder will only contain subfolders with a copy of the files in the parent directory (your working files, your code !).

 

More pointers :

 

Databases

Working with databases implies working with queries. When building a query, and for optimization reasons, you won't always do a

SELECT * FROM TABLE

this query means : stock every value of every column of every row of the table 'TABLE' into the memory.

But most of the times you'll go for something like that

SELECT c_name, c_lastname, c_address, c_zip, c_town from CUSTOMERS where c_country='US'

which means : stock only name, last name, address, zip code and town of the customers living in USA.

When browsing the results, you will have to access the fields of the rows by a number (index) of the element in the row, this being relative to the order you've SELECTed them. So it's a really good habit to always keep track of your queries in a chart.

 

For example:

 

QUERY NAME : qry_us_customers

TYPE : SELECT (if it is such a query, UPDATE, DELETE OR INSERT for the major other ones.)

TABLE : CUSTOMERS

FIELDS:

0:c_name

1:c_lastname

2:c_address

3:c_zip

4:c_town

CONDITIONS

c_country = 'US'

ORDER

None

 

so wherever you're in your code, when you use this query, a quick peek at your charts reminds you that to access the zip code, you'll have to pick index #3 (count starts at 0) :

zipCode = result[3]

Excel makes wonders for this :)

 

Did you notice that the fields are prefixed with a c_ like CUSTOMERS ?

 

Many languages offers some functions which returns an 'evoluted' charts with the values in it. You can then call the value you need by specifying the name of the column (the name of the field in the database), in this case, "c_zip" like this :

echo $result[`c_zip`]; (php)

 

Naming conventions

 

These are the most often used :

 

  • CONSTANTS IN UPPER CASE !
  • Variables in Capitalized words except the first one always starting with a letter, no accent, no special character except underscore "_"
    • customerName is ok
    • customerName2 is fine
    • 2customerName is wrong (some languages can't handle a variable name starting with a number)
    • CustomerName will work but isn't really normalized (who cares :)!:))
    • customer_Name is ok
    • the_Name_Of_The_Customer is stupid because it's really too long and will make you waste a lot of time when coding
    • cN is also stupid, because it is not self explanatory enough.

My conventions :

  • string variable names start with a s_ : s_Name = 'Nihilith'
  • integer variable names start with a n_ : n_Age = 31
  • float variable names start with a f_ : f_AccountBalance = 0.10 (time to get some more work...)
  • a database table field starts with a letter or two reminding the table name : 'c_zip' in 'CUSTOMERS' table
  • a database table names are prefixed with a reminder of the database name. not used in the previous examples, to simplify the reading !

It can occur that 2 databases used in the same project, and thus, merged into a unique database, have tables that have the same name. Imagine you merge a blog database with a 'comment' table with a photo gallery database with a 'comment' table... all the tables coming from the blog database will be prefixed with b_ (b_comment) and all the tables from the photo gallery with pg_ (pg_comment) so the 2 'comment' tables can exist together

 

Prefixing is a really good habit (one more) because, you know where the data comes from, and regarding variables, you know what type of data you're dealing with, and thus, won't try to divide a float by a string !

 

and so on when using widgets (GUI objects) such as with gtk widgets and python, I use a prefix reminding the type of widget :

 

  • btn_ for a button : btn_Quit
  • ent_ for a text entry : ent_Login
  • win_ for a window : win_MainWindow
  • tv_ for a tree view : tv_CustomerList

There are standards, but once you've found a naming convention that fits your needs, always be strict and make a rigorous use of it. Never, never go fancy with naming convention. When browsing 15000 lines of code for all the calls to the button widgets, you just have to search "btn_" and even notepad can handle such a difficult search.

 

Libraries

I often talk about libraries. Here's a quick description of what they are, and what they do.

Libraries are programs that have been build to be used by others programs, meaning they can't be run by themselves, you must invoke it in your program and access its functions in your program. The library will then send you a result back, in the form of a variable or a process (printing, displaying, controling a robot).

DLLs are library, offering the system some functions and called by other programs. You can't run a dll directly. One famous dll is directx.dll (voluntarily mispelled) which offers 3D management to Windows and which is used by almost all your favorite games. You graphic card driver is a library, a dll, that translates a standard order given by the OS into a language that your CG card understands, resulting in displaying something on the screen. A game sends a command to directx.dll, redirected to the OS then to your CG card driver and resulting in displaying something on the screen...

We're talking about layers, to be exact, these are called abstraction layers. You don't have to know what your CG card understands, and you don't have to know what your CG driver is waiting for. You just have to know what directx is waiting for. You can make abstraction of the rest. When you ask directx to display a cube, that's a hundred of commands at directx level that are involved (creating the points, the edges, the faces, the color, placing it in a 3D coordinates system), maybe a hundred commands at the os level, the same amount at the driver level... More than offering abstraction, libraries also simplify the code !

 

When coding, never try to invent the wheel again (sorry, but this my own translation of a french quote). Try to find a library that does what you want for you, instead of typing lines and lines of code. You'll save time, coffee and your nerves. Be careful as libraries may be protected by copyrights and can't be used for a commercial purpose for instance.

Engines

It's difficult to talk about libraries without leaving a note about engines. Engines are 'super' libraries that offer a pack of libraries to handle several functions. A game engine for instance will take care of :

  • Inputs (keyboard, mouse)
  • Display
  • Sound
  • Video
  • Collision between the objects
  • Networking
  • ...

I won't go any further about engines. It's a subject on its own, and I'm not really familiar to engines...

 

 

Conclusion

 

Ok, this is a quick overview of what I should call a quick start to organized programming. Feel free to comment and ask questions. I may update this guide often and according to the relevant questions.

 

Patience over everything else is the first key...

Cream for wrist injuries...

No rough coding...

Slowly but fully...

Strict respect of the conventions YOU have choosed !

Use libraries, and study them if you got access to the source code. They will work for you, and can teach you the way to fix a bug, or teach you things you never ever thought about.

 

 

 

Hope it helps

 

[Edit] : Typos ! grrrrrr and also fixed the crappy lists ! And major update with more naming convention + highlighting + bold + whatever... this finally looks like a guide :( + notes about libraries and engines... abstraction layers...

Edited by Nihilith
Link to comment

Very nice guide Nihilith. It's excellent for us relatively new to programming. I like that the point you've made most important here is preparation and organization. I'm sure that for experts it is easy enough to just jump right into programming with a goal in mind but for a novice I can see how important it is to set up a strategy.

Noteworthy guide Nihilith. While I understand the creative aspects of programming I think this would be much better suited in Tech Talk. Since we don't as yet have a specific section for programming in Tech Talk I'm going to create it now and sticky your guide there. Hopefully it will inspire others to create their own unique coding styles and projects. :drinks:

 

Personally I'm most intrigued about your section that mentions databases and queries. Here at DarkMatters our database is enormous with plenty to work with. I'm itching to do something creative with it. In fact I already did think of an idea that would be cool. A somewhat automated Sacred Roster. I've been debating the use of either Actionscript or sql/php/html and I think I'd like to try sql/php/html. The idea would be to create a new page with functions that are most closely based on forum user groups here at darkmatters. As it is presently all clan members are in the Fellowship group. I'd like the new page to basically import data from the Fellowship group and place them visually within two columns. I'd also like to create a new custom field that would allow any member of Fellowship to type out a description on their profile page which would be imported onto the roster page. Many of the constants and variables are already created which cuts the workload quite a bit.

 

Before I yammer on any further I think I'll give your guide a try and start penciling in those ideas. Very nice work Nihilith. I'm glad you're here! :drunkards:

Link to comment

To be exact Brad, even for a pro dev, the pen/paper combo is an absolute need. I should say, it is more and more needed as you grow up in coding, because you have to deal with enormous projects with a lot of constraints. When dealing with databases, there are points like foreign key constraints or dependencies that need a lot of thinking before getting coded. A pro dev, most of the time works in a team, or directly with the customer (my case), so coding roughly from a customer idea is suicide, and coding without a plan in a team is genocide !

 

Dealing with the Hello World app isn't such a pain, you can start it from scratch in any language. But even for such a simple prog, getting used to write down what it takes is a good habit to have.

 

For the roster, if you want to get a graphical layout, you can go either into flash with action script or php with the image plugin which handle a lot of functions as it inherites its code from imagemagick, the most powerful image library right now. Php image module can resize, insert watermarks (so text overlay isn't a problem), crop images and so on. You can achieve a sig generator and a classy roster layout with just php and html.

 

Write, draw, archive, but don't either erase nor trash your drafts. This is the key to success. Coding is just icing on the cake (or the chocolate nugget in da cookie), the binary expression of your hard "mind" work, your award, not your weapon. Coding is so easy when everything is planned, imagined, written. If you can't see the way to do it, do it differently, but there's always a solution. Don't think about optimization first, think about result. Once you got what you want you can get it faster, but fill the blanks, reach the goal first. It's like practicing an instrument (and as a beginner guitar player I can only approve it). Start slowly, like a snail, and go through all the song to the end. It sounds like crap. Start again, slowly, till the end. Yes 1 chord is ok now... once again, 2 chords right... the whole slowly paced song... then the song, at full speed. But everytime, you reach the goal, playing the song slowly, badly, better, well, fast...

 

You already did wonders with the forum and the wiki Brad. If you give yourself enough time to plan your project, it will be a piece of cake !

 

Thanks for the sticky !

Edited by Nihilith
Link to comment

Really nice guide. Im going to use this method and make a simple calculator in python.

 

I didnt expect that there was so much work to be done, before actually starting to write the program.

 

Man I can already see myself going crazy once I start this at school :oooo: , and its 6 months away!

Link to comment
Major update :D

 

Very nice changes and additions Nihilith. It reads even better now. The lists in particular help a lot.

 

 

Really nice guide. Im going to use this method and make a simple calculator in python.

 

I didnt expect that there was so much work to be done, before actually starting to write the program.

 

Man I can already see myself going crazy once I start this at school :) , and its 6 months away!

 

Great project idea moo. That sounds like a great way to get started. :)

Link to comment
  • 9 months later...
  • 6 years later...

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...
Please Sign In or Sign Up