|
I understand your comment better than the initial statement in the article, particularly in light of your example. You example simply restates in English WHAT your code is doing, it even clarifies for how long, but not why. This is a good example of a comment that could later on contradict the code if a need to change the timing arises, but the comment isn't modified.
|
|
|
|
|
I wish I could disagree. When you are debugging some legacy code all you have are the source and the comments. The comments are all lies. The documents are neatly typed ceremony and also lies.
Half the methods are never called , of the ones that are called half have branches that are never called and have variable names like xmlTheRealOne.
Then I read on code project about comments and I wonder does any code exist with true comments in it?
|
|
|
|
|
Generally agree...
First of all I would like to say that some of this may not relate to every programming language...
2.
Duncan Edwards Jones wrote: A good indication that you have got the level of comment right: could someone understand what your program is intended to do if all but the comments were removed?
I don't think so ... I think that comments are VERY important, but should complement code, not be a "psudo replacement" for it (for readability obviously).
If a block is completely understandable by itself why bother ... eg: why bother commenting a one line function called TrimTabsOnly
3.
Duncan Edwards Jones wrote: Code should be split across files
Defiantly agree my solutions always have many solution folders, partial classes, and projects within them... some people (particularly seem to) hate that I have so many projects in my solutions, but in large solutions they can also decrease build time ALOT.
IMHO partial classes and multiple projects for different components / controls etc are defiantly under-used by most of the programming populous.
4.
Duncan Edwards Jones wrote: Try to work out what conditions could cause your code to fail and test for them before they cause the program to fall over.
And now for the other end of the spectrum ... error handling is something many programmers OVER-use!
... a good programmer, like you said, will A. handle errors BEFORE they occur, B. know when to use error handlers to capture "expected" exceptions, and if an error is NOT expected somewhere then there should be no handler at all!
Unhandled exceptions can be useful (for debugging of course); I have seen too many programmers putting try catch blocks around MOST of their code just for the sake of it, and then wonder where the error actually occurs because they have a message box that shows the error. People tend not to want to show the callstack to the end user in error handlers, and this I agree with, instead just leave the errors unhandled and let the built in unhandled exception handler throw them or build your own that shows you nicer information about the error (call stack here is OK). If you have done A and B correctly, you will have none or minimal unhandled exceptions anyway.
5, 6 Agree
7.
Classes within classes (no not subclassing : )
This is another widely underused "feature" ... I even believe that Microsoft is a culprit of this... and I know that I will probably be flamed for this ... but...
If a class is used widely in another class and relates directly to it then don't be afraid to put the class in the class it is used in... if you think it is messy all being in one file READ 3. AND RESEARCH PARTIAL CLASSES.
Eg of MS being a culprit too...
TreeNode relates directly to treeview ... so IMHO a new node should be defined like this:
Dim TestNode As New TreeView.TreeNode
Let me know if you agree or disagree ... just giving my two cents
Kris
modified 6-Nov-14 18:18pm.
|
|
|
|
|
Yes - and in the TreeView example if the TreeNode only makes sense in a treeview then there should be a Create factory in TreeView and no public constructor.
|
|
|
|
|
Sorry I am not sure if you were being sarcastic or not?...
I don't agree with this, that also means that you cannot inherit from it.
Kris
|
|
|
|
|
A good point. This is harder than it looks
|
|
|
|
|
Hmm, at first look it seems a bit like Captain obvious to the rescue, but it's a good list (that I fail frequently to follow and therefore it can be assumed that others do aswell)
and I don't understand the mass of downvotes, so allow me to compensate a bit.
|
|
|
|
|
It was originally written about 12 years ago - but I have had a total reversal on some points so edited it accordingly.
Thanks for the feedback
|
|
|
|
|
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
|
|
|
|
|
I think the comment ' STUDENT_TODO pretty much covers my response.
'--8<------------------------
Ex Datis:
Duncan Jones
Merrion Computing Ltd
|
|
|
|
|
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.
|
|
|
|
|
|
|
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
|
|
|
|
|
|
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.
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|
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
|
|
|
|
|