|
|
1. Code for human consumption
It is one of the most pervasive misunderstandings in computing that the source code is for the computer's consumption. Computers work with low-level binary code, a series of impenetrable 1's and 0's or hexadecimal numbers, not the structured high level languages we code in. The reason that these languages were developed was to help the programmer.
In practice, coding for human consumption often means coding for clarity first, over efficiency and speed second.
2. Comment often and comment well
The comment is the extreme example of a language element for human consumption. Most compilers will strip the comments from the executable program. The purpose of the comment is to tell you (and any future developer) what the program is intended to do. Write comments with this in mind - and avoid simply restating the code.
- Good comment: Disable button to prevent its activation.
- Bad comment: Set cmd = False
A good indication that you have got the level of comment right: could someone understand what your program does if all but the comments were removed?
3. Layout code to increase legibility
Just as it is important for an author to split a book into chapters and paragraphs that aid reading so it is important for the developer to consider the layout of the code and how that can aid readability of the code. In particular, any code branch (an IF..THEN...ELSE construction) and any code repetition (a WHILE...END WHILE construction) should be indented so that it is easy to see where they start and end.
4. Expect the unexpected and deal with it
Before you open a file, make sure that the file is present. Before you set focus to a control, make sure that the control is visible and enabled. Try to work out what conditions could cause your code to fail and test for them before they cause the program to fall over. Also use explicit data type conversion wherever possible.
5. Name your variables to aid readability
There are a number of strategies to variable naming. The key is to be consistent and to be as informative as possible. If you name a variable nMonth, you give the programmer extra information as to what that variable is expected to contain. I personally prefer the Hungarian notation style - but whichever style you use, consistency is the key.
6. Keep your functions and subroutines simple
A function or subroutine should ideally only do one thing. One of the greatest sources of misunderstandings, in my experience, is a subroutine that does a number of different operations. This should be split into separate functions for each different thing it is doing, so that these in turn are easy to reuse, and the scope of a code change is easy to understand.
7. Scope functions and variables appropriately
Functions and variables that are only used in one module should not be visible outside that module. Variables that are only used in a function or subroutine should not be visible outside that function or subroutine. This prevents any use of a variable or function outside of where it makes sense to use it.
| You must Sign In to use this message board. |
|
| | Msgs 1 to 25 of 93 (Total in Forum: 93) (Refresh) | FirstPrevNext |
|
|
 |
|
|
I need help in VB6 with one my projects !
Sub Main()
Const PhysicalSize As Integer = 2500
Dim Inventory(PhysicalSize - 1) As InventoryItem, LogicalSize As Integer
' 1. Load the data from the Inventory File into the array
LoadInventory Inventory, LogicalSize, PhysicalSize
' 2. Process Discontinued Inventory
ProcessDiscontinuedInventory Inventory, LogicalSize
' 3. Process New Inventory
ProcessNewInventory Inventory, LogicalSize
' 4. Process Discounts
ProcessDiscounts Inventory, LogicalSize
' 5. Save the data in the array to the Inventory File
SaveInventory Inventory, LogicalSize
End Sub ' End Main
'_____________________________________________________________
'=============================================================
' LoadInventory
' Purpose:
Sub LoadInventory(ByRef Inventory() As InventoryItem, _
ByRef LogicalSize As Integer, _
ByVal PhysicalSize As Integer)
Open App.Path & "/Inventory.csv" For Input As #1
LogicalSize = 0
Do While Not (EOF(1)) And LogicalSize < PhysicalSize
With Inventory(LogicalSize)
Input #1, .PartNumber
Input #1, .Description
Input #1, .ISBN
Input #1, .Author
Input #1, .Edition
Input #1, .SellingPrice
Input #1, .OnHand
Input #1, .OnOrder
End With
LogicalSize = LogicalSize + 1
Loop
Close #1
End Sub ' End LoadInventory
'_____________________________________________________________
'=============================================================
' SaveInventory
' Purpose:
Sub SaveInventory(ByRef Inventory() As InventoryItem, _
ByVal LogicalSize As Integer)
Dim Index As Integer
Open App.Path & "/Inventory_Out.csv" For Output As #1
For Index = 0 To LogicalSize - 1
With Inventory(Index)
Write #1, .PartNumber, _
.Description, _
.ISBN, _
.Author, _
.Edition, _
.SellingPrice, _
.OnHand, _
.OnOrder
End With
Next
Close #1
End Sub ' End SaveInventory
'_____________________________________________________________
'=============================================================
' ProcessDiscontinuedInventory
' STUDENT_TODO
' Purpose:
Sub ProcessDiscontinuedInventory(ByRef Inventory() As InventoryItem, _
ByRef LogicalSize As Integer)
Dim FoundPosition As Integer
Dim DiscontinuedPartNumber As Long
Dim Index As Integer
Dim DeleteItem As Integer
Dim FoundItem As Integer
Open App.Path & "\Returns.csv" For Output As #1
Open App.Path & "\DiscontinuedInventory.csv" For Output As #2
Index = 0
FoundPosition = FindPartNumber(Inventory, LogicalSize, DeleteItem, FoundPosition) < -- I GET A ERROR OVER HERE SAYIN EXPECTED FUNCTION OR VARIABLE NAME !! and the rest of the code where im calling a function!
If Inventory(FoundItem).OnHand > 0 Then
Write #1, Inventory(Index).Author, Inventory(Index).Description, Inventory(Index).Edition, _
Inventory(Index).ISBN, Inventory(Index).OnHand, Inventory(Index).OnOrder, _
Inventory(Index).PartNumber, Inventory(Index).SellingPrice
DeleteItem = OrderedDelete(Inventory, LogicalSize, DeleteItem)
End If
Close #1
Close #2
End Sub ' End ProcessDiscontinuedInventory
'_____________________________________________________________
'=============================================================
' ProcessNewInventory
' STUDENT_TODO
' Purpose:
Sub ProcessNewInventory(ByRef Inventory() As InventoryItem, _
ByRef LogicalSize As Integer)
Dim FoundPosition As Integer
Dim NewInventory As InventoryItem
Dim Index As Integer
Dim InsertItem As Integer
Index = 0
Open App.Path & "\NewInventory.csv" For Output As #1
Open App.Path & "\DuplicatePartNumbers.csv" For Output As #2
FoundPosition = FindPartNumber(Inventory, LogicalSizem, SearchPartNumber, FoundPosition)
If FoundNumber > 0 Then
Write #2, Inventory.PartNumber, Inventory.Description, Inventory.ISBN, _
Inventory.Author, Inventory.Edition, Inventory.SellingPrice
Else
InsertItem = OrderedInsert(Inventory, LogicalSize, InsertItem)
End If
Close #1
Close #2
End Sub ' End ProcessNewInventory
'_____________________________________________________________
'=============================================================
' ProcessDiscounts
' STUDENT_TODO
' Purpose:
Sub ProcessDiscounts(ByRef Inventory() As InventoryItem, _
ByVal LogicalSize As Integer)
Dim FoundPosition As Integer
Dim PartNumber As Long, SellingPrice As Currency
Open App.Path & "\Discounts.csv" For Output As #1
Open App.Path & "\FailedDiscounts.csv" For Output As #2
FoundPosition = FindPartNumber(Inventory, LogicalSize, PartNumber, FoundPosition)
If FoundPosition > 0 Then
Write #2, Inventory.PartNumber, Inventory.SellingPrice
End If
End Sub ' End ProcessDiscount
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
|
|
|
A programming book that all programmers should read is Code Complete by MS Press. It shows many pitfalls, and way around them. It also shows the best practices to create code in an open architecture way that minimizes code changes as specs change.
|
| Sign In·View Thread·PermaLink | 3.40/5 (2 votes) |
|
|
|
|
|
|
|
|
|
You asked, could someone understand what your program does if all but the comments were removed?
Yes, because at that point it wouldn't do anything.
Mike
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
|
|
|
As I see it there are three types of comment.
Firstly you've got "how" comments that explain what the code does. In general, I'm finding (with more modern languages in particular), that the "how" comments are becoming less relevant, as code layout, variable/procedure naming, etc. can show the "how" quite well by themselves.
The second type of comments are the "why's". Recording why a particular piece of code was written, why a certain condition is checked. I've found in maintaining code that it's usually a straight-foward process to find where a procedure is causing a problem. Quite often though, the code was deliberate and now no-one that knows why that code was written. Even a reference to a business requirement, or a functional spec chapter would be a help.
Finally we get to the "who's". Who made the change (name or at least department). This is mainly a fallback when trying to find the "why's".
I've found that software has a substantially longer lifetime than any associated documentation, and without the "why" fixing a small problem in one area of an application can cause down-stream processes to fail.
Of course, with full regression suites and sufficient time/money to run the end-to-end tests this wouldn't be a problem, but I don't think many of us will have seen that with legacy code.
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
garyknights wrote:
The second type of comments are the "why's". Recording why a particular piece of code was written, why a certain condition is checked. I've found in maintaining code that it's usually a straight-foward process to find where a procedure is causing a problem. Quite often though, the code was deliberate and now no-one that knows why that code was written.
I fully agree. Having just finished a maintenance contract, and having done a lot of maintenance over the years, I would say that this is the biggest single failing in code commenting among developers. I try to make a habit of providing "why" comments with my own code - if only for myself when I have to look back at it in a year's time. Even then I often have to scratch my head!
Kevin
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Those "secrets" are mostly all cosmetic. You can and you will see programmers following all of these and still fail on many fronts. Programming is a science, not an art.
It is my believing that just like in any fields, there are "naturals" which get it right without much efforts because it is common sense for them. About the only thing they need is willpower and experience.
There are exceptions to this, but I think it holds true for the majority of "successfull" programmers.
Please note that having good social skills, good contacts and the proverbial "being at the right place at the right moment" don't hurt either.
Sébastien
Intelligence shared is intelligence squared.
Homepage : http://www.slorion.webhop.org
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
I agree. The "seven secrets" deal mostly with coding style. We all know successful programmers who could care less about style. Not to diminish it's importance, but style really only helps with maintenance and reuse. I write embedded software for the automotive industry, and there is one big key to success here - process. Call this my not-so-secret secret to success.
Our process goes something like this (you may recognize this as the classic "V" diagram):
1. Requirements - know what your software should do before you start coding.
2. Design - Translate the requirements into an architecture or structure which can meet the requirements, given the system constraints.
3. Implementation - The fun part that we all live for (coding).
4. Verification - Testing our code, does it meet the requirements? This should be done by someone other than the software creator. If the requirements are unclear, two people might interpret them differently.
5. Issue tracking / change management - We find the majority of problems come from late changes to the requirements, A.K.A. creeping elegance. This takes discipline to know when there's real value in a change or when it's not worth the risk.
Sure it helps to be a "natural". Maybe a process is just common sense, but given a good process, the only difference between a "natural" and a mear mortal is their level of productivity, not their success.
Tom
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
While the process you mention is good and wildly known (but not necessarily wildly used mind you), it merely ensures that the black box you designed works correctly and meets requirements. It tells nothing about the quality of the design and implementation. Also, it supposes that initial design and implementation will be right, which certainly is not always the case. All in all, the V diagram is very basic and is the least one can do. While iterative processes offer some more flexibility, they do not state anything about the design and implementation quality either.
Sébastien
Intelligence shared is intelligence squared.
Homepage : http://www.slorion.webhop.org
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Sébastien Lorion wrote:
While the process you mention is good and wildly known (but not necessarily wildly used mind you), ...
Sébastien,
Did you really mean wildly or widely? Interesting twist that I’m sure applies to some programmers. To be pragmatic, my employer doesn’t rate my performance on the quality of my design and implementation, rather whether my deliverables are there on time and meet their requirements.
The fact that the “V diagram is very basic and is the least one can do” yet it is not “widely used” is the exact reason I brought it up. Too many of us rely on add-hoc processes and heroic last minute efforts to get products out the door. A disciplined design methodology, although common sense to us, is the first thing we abandon when things get tight,
Certainly, the “V diagram” must be iterative. I prefer to think of it more as a spiral passing through the quadrants of specification, design, implementation and test towards the center. With each revolution the changes become smaller until you reach your target.
I don’t want to downplay the importance of good design and implementation practices. One way to promote them is through peer reviews.
Tom
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
LOL, yes I meant widely, but looking at it, it's a pretty fun typo 
What you are stating about your employer is sad to hear as I know it's the rule, not the exception. Call me idealistic if you will (some do), but quality should be a part of the equation. Not the only criteria, but it should be considered to its right importance. The problem : who is going to judge the quality ?
Sébastien
Intelligence shared is intelligence squared.
Homepage : http://www.slorion.webhop.org
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Quality is judged in the maintenace phase. Or to be more precise the lack of quality!
I have seen examples of deliverables produced extremely fast. Initial bussiness perspective, wow we can make money here delivering faster and chaeper.
Then maintenance kicked in. Far more time and money was spent to correct all lack of quality in the original program. At that stage, and only just then, the management understood the need for quality. Well atleast to the level that lack of quality isn't bad, as long as it keeps proffitable.
cheers,
Paul
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Tom Pruett wrote:
Not to diminish it's importance, but style really only helps with maintenance and reuse.
But those are not unimportant tasks!
Kevin
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Sébastien Lorion wrote:
Those "secrets" are mostly all cosmetic. You can and you will see programmers following all of these and still fail on many fronts.
That's true. But they're still important things to get right. It's just that they're not all there is. But the title of the article is misleading as it suggests that these are the key to successful programming, rather than being part of the requirements.
Sébastien Lorion wrote:
It is my believing that just like in any fields, there are "naturals" which get it right without much efforts because it is common sense for them. About the only thing they need is willpower and experience.
I get the impression that, while there will always be a handful of programmers who are naturally way better than everyone else, in most cases successful programming is down to attitude rather than ability. A lot of programmers know better but are just sloppy. But maybe that attitude of being sloppy or not is a natural characteristic.
I don't think I'm especially great at programming - probably fairly average, in fact. But I just try hard to follow the recommended practices of whatever language I'm using, have consideration for my fellow developers who must maintain my code and so on.
Sébastien Lorion wrote:
Please note that having good social skills, good contacts and the proverbial "being at the right place at the right moment" don't hurt either.
You bet! Never seems to happen to me though.
Kevin
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
I pretty much completely disagree with point #2. Code should be self-documenting. It should be written in such a way that you dont *need* comments to understand what's going on. A good litmus test is if an intelligent non-programmer can get the gist of what's going on by reading your uncommented code, you've done a good job of writing it.
One my #1 ways of recognizing poor coders is by the volume of comments they add. It seems like newbie coders comment a lot and more experienced coders produce elegant, readable code that doesn't require a lot of comments.
|
| Sign In·View Thread·PermaLink | 5.00/5 (2 votes) |
|
|
|
|
|
|
This quickly devolves into "if I can understand it when I wrote it, it's commented enough". Fine for you today, not so fine six months from now when you (or somebody else) go back into that obscure routine.
Try reading a complex algorithm's code with "self-commenting code" and you'll see what I mean.
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
rondalescott wrote:
I pretty much completely disagree with point #2. Code should be self-documenting. It should be written in such a way that you dont *need* comments to understand what's going on. A good litmus test is if an intelligent non-programmer can get the gist of what's going on by reading your uncommented code, you've done a good job of writing it.
Good comments, tell you why something is being done and not what is being done. With 90% of code, you should be able to tell what is happening by reading the code. Why something is being done (a certain way) is what you need to comment. This makes it easier when you come back to code later.
rondalescott wrote:
One my #1 ways of recognizing poor coders is by the volume of comments they add. It seems like newbie coders comment a lot and more experienced coders produce elegant, readable code that doesn't require a lot of comments.
Again, it depends on the kind of comments. If you have a lot of
// Increment count
nCount++
type comments, the I'd agree - but comments stating why are very important.
Michael
'Logic, my dear Zoe, merely enables one to be wrong with authority.' - The Doctor: The Wheel in Space
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
Michael P Butler wrote:
Good comments, tell you why something is being done and not what is being done. With 90% of code, you should be able to tell what is happening by reading the code. Why something is being done (a certain way) is what you need to comment. This makes it easier when you come back to code later.
Exactly right, Michael. And the absence of "why" comments is the biggest deficiency among developers in my experience.
I agree with rondalescott in that code should be as self-documenting as possible, i.e, choose readable names, etc. However, apart from the "why" comments it is still helpful to have brief inline summary comments, such that you can get a good idea of what's going on just by reading the comments. It also makes it easier to subsequently refactor the sections into their own well-named routines, thus eliminating the comments.
OTOH, if you have too many comments there's always the danger of the comments getting out of synch with the code. But this is never completely avoidable.
Kevin
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
And don't forget the "Why not" comment.
Another developper may have the idea to do it another way. But you have tried this way already and failed. If you comment this failed way you save the next developper to waste time.
Dani
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
>>Code should be self-documenting
I don't want to read the code of a function just to understand what it is doing. The name of the function (also the parameters) and the corresponding comment are important to understand whats going on in that function.
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
I also quite disagree with Point #2.
Comments are very tricky because they often are not updated. I've seen many times the following happen many times.
When the code is written from sratch, the author comments very nicely. Then bugs fixing comes in the process and modifications in the code are made without updating the code (developpers hate bugs in their code and try to fix them as quickly as possible!). In the end the comments don't make sense at all.
I think this is much worse than no comment at all and frankly it happens all the time.
I believe in short functions that do a simple task and have a proper name describing precisely the task.
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
Yes, keeping comments up-to-date is a perennial problem. The rule should be: "comments should be as many as required but as few as possible."
Arnaud Brejeon wrote:
I believe in short functions that do a simple task and have a proper name describing precisely the task.
One of developers' biggest failings is having over-long routines. I've just finished maintaining code that typically had routines spanning several A4 pages in length. I think what happens is that developers may start out with good intentions. But then routines get more complex as problems are found or as new developers have to maintain it. What they should do is refactor their changes into new helper routines so that the original remains short. Not always as easy as it sounds though.
One way of getting to fewer comments is, ironically, to have lots of section summary comments when you're developing a routine. This makes it easier for you to subsequently refactor those sections into their own routines which are named after the comments. Then you can eliminate the comments, leaving self-documenting code.
Kevin
|
| Sign In·View Thread·PermaLink | 5.00/5 (1 vote) |
|
|
|
|
|
|
Kevin McFarlane wrote:
One of developers' biggest failings is having over-long routines.
Oh yes!
And I am guilty of that myself.
It simply gets longer as more and more special cases have to work with this one method.
Here, tools for semi-automatic refactoring would come in very handy.
Is there such a tool for C++?
I know it is for Java.But who wants to program Java? *duck&run*
Who is 'General Failure'? And why is he reading my harddisk?!?
|
| Sign In·View Thread·PermaLink | |
|
|
|
|
|
|
 General  News  Question  Answer  Joke  Rant  Admin
|
