21,662
-
:laugh: I have a colleague at work whose Classes kind of look like that...
Public Class MyClass
Sub DoSomething
' This code is to... (obvious comments) Dim i as Integer ' (actual code here) ' Assign a value to the integer (more obvious comments) i = 10End Sub
Sub NextMethod
' etc.End Sub
End Class
That's at least one white line between each line of comment/code. It is also the kind of comments you don't want to see (assign value... No shit, Holmes!). Between the last lind of code and End Sub/Function are usually two or three empty lines of code. Between each Method can be three to five lines of white space and between the last Method and the End Class can be up to seven(!) white spaces (I've analyzed his code pretty deep :) ). Also notice the lack of access modifiers? I asked him about that and they were all meant to be Private... It's just lazyness on his part to not make those Methods Private like they are meant to be! :^) Luckily there aren't usually more than 300 to 400 lines of code (including empty lines) so I guess I shouldn't complain to hard :laugh:
It's an OO world.
public class Naerling : Lazy<Person>{}
Ouch. I use lots of white space, but not that much. I actually have very strict guidelines for how I use whitespace in my code (in VB.Net, I used 0-2 blank lines between things, depending on the situation). And I actually make very obvious comments in my code. To me, comments are not only to describe the code, but they help me read the code faster, which means comments and whitespace should be both very consistent and should describe each section of code. So I might have:
''' <summary>
''' Information about an animal.
''' </summary>
Public Class Animal#Region "Constants"
Private Const HIGHLANDER As Integer = 1
Private Const BUNCH_MIN As Integer = 10
Private Const COUPLE_NAME As String = "couple"
Private Const BUNCH_NAME As String = "bunch"
Private Const TEMPLATE_DESCRIPTION_SINGLE As String = "There is one baby {1}."
Private Const TEMPLATE_DESCRIPTION_MANY As String = "There are a {0} of baby {1}s."#End Region
#Region "Properties"
''' <summary>
''' The name of this type of animal (duck, hamster, ...).
''' </summary>
Public Property AnimalName As String#End Region
#Region "Methods"
''' <summary>
''' Gets a description of the number of children this animal has.
''' </summary>
''' <param name="count">The number of children.</param>
''' <returns>The description ("There are a couple of baby ducks.").</returns>
Public Function GetChildrenDescription(ByVal count As Integer) As String' Variables. Dim description As String Dim countWord As String ' Choose description based on number of children. If count = HIGHLANDER Then description = String.Format(TEMPLATE\_DESCRIPTION\_SINGLE, Me.AnimalName) Else If count >= BUNCH\_MIN Then countWord = BUNCH\_NAME Else countWord = COUPLE\_NAME End If description = String.Format(TEMPLATE\_DESCRIPTION\_MANY, countWord, Me.AnimalName) End If ' Return description of children. Return descriptionEnd Function
#End Region
End Class
So even though "variables" is obvious, I still keep it there because it allows me to read through code faster (e.g., by skipping over the section with var
-
Ouch. I use lots of white space, but not that much. I actually have very strict guidelines for how I use whitespace in my code (in VB.Net, I used 0-2 blank lines between things, depending on the situation). And I actually make very obvious comments in my code. To me, comments are not only to describe the code, but they help me read the code faster, which means comments and whitespace should be both very consistent and should describe each section of code. So I might have:
''' <summary>
''' Information about an animal.
''' </summary>
Public Class Animal#Region "Constants"
Private Const HIGHLANDER As Integer = 1
Private Const BUNCH_MIN As Integer = 10
Private Const COUPLE_NAME As String = "couple"
Private Const BUNCH_NAME As String = "bunch"
Private Const TEMPLATE_DESCRIPTION_SINGLE As String = "There is one baby {1}."
Private Const TEMPLATE_DESCRIPTION_MANY As String = "There are a {0} of baby {1}s."#End Region
#Region "Properties"
''' <summary>
''' The name of this type of animal (duck, hamster, ...).
''' </summary>
Public Property AnimalName As String#End Region
#Region "Methods"
''' <summary>
''' Gets a description of the number of children this animal has.
''' </summary>
''' <param name="count">The number of children.</param>
''' <returns>The description ("There are a couple of baby ducks.").</returns>
Public Function GetChildrenDescription(ByVal count As Integer) As String' Variables. Dim description As String Dim countWord As String ' Choose description based on number of children. If count = HIGHLANDER Then description = String.Format(TEMPLATE\_DESCRIPTION\_SINGLE, Me.AnimalName) Else If count >= BUNCH\_MIN Then countWord = BUNCH\_NAME Else countWord = COUPLE\_NAME End If description = String.Format(TEMPLATE\_DESCRIPTION\_MANY, countWord, Me.AnimalName) End If ' Return description of children. Return descriptionEnd Function
#End Region
End Class
So even though "variables" is obvious, I still keep it there because it allows me to read through code faster (e.g., by skipping over the section with var
That's looking pretty decent. I must admit I never use Constants myself. But looking at this they are actually pretty handy. My code would say If count = 1 Then... And I often find myself commenting what 1 is or why we would have it. I am also a big fan of XML comments. Especially when I am developing some Class Library for my company to use (and I do that from time to time). I wouldn't put any of the comments in the GetChildrenDescription Method though. It looks all pretty self explanatory to me ;)
It's an OO world.
public class Naerling : Lazy<Person>{}
-
That's looking pretty decent. I must admit I never use Constants myself. But looking at this they are actually pretty handy. My code would say If count = 1 Then... And I often find myself commenting what 1 is or why we would have it. I am also a big fan of XML comments. Especially when I am developing some Class Library for my company to use (and I do that from time to time). I wouldn't put any of the comments in the GetChildrenDescription Method though. It looks all pretty self explanatory to me ;)
It's an OO world.
public class Naerling : Lazy<Person>{}
Yeah, constants are nice for refactoring. It is easy enough to search the code for "10" and change it, but you may not want to change every "10" and there may be a bunch of them. Assigning it to a constant allows you to change it in one place. For some things that are unlikely to ever change (such as "HIGHLANDER"), I might just use a magic variable (i.e., no consant), and I have no problem with code that does that in those cases. Heck, I even use magic variables when I'm just lazy, but will sometimes go back later to convert them to constants or properties or whatever is appropriate. Really they're just one of those "nice to have" things that make others smile when they see your code (or indeed when you see your own code months after you write it), because it's so effortless to maintain. By doing these good practice things as often as possible (even when they are not strictly necessary), I find that they have become instinct and it's not hard at all to do things the right way most of the time. Good practice practice practically makes perfect good practice. :)
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
I just asked a coworker where in TFS the source code is for a utility that is heavily used in our department. He said it wasn't, but he'd email me the source code. :(( It is a Windows Forms application and there are several forms, but there is one primary form. I looked at the VB (.Net, thankfully) code for that form. I wish I hadn't... 21,662 lines of code, just for that one form. :(( Now, I just have to figure out what Form2, Form3, Form4, Form5, Form6, and Form7 do. :((
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
That's looking pretty decent. I must admit I never use Constants myself. But looking at this they are actually pretty handy. My code would say If count = 1 Then... And I often find myself commenting what 1 is or why we would have it. I am also a big fan of XML comments. Especially when I am developing some Class Library for my company to use (and I do that from time to time). I wouldn't put any of the comments in the GetChildrenDescription Method though. It looks all pretty self explanatory to me ;)
It's an OO world.
public class Naerling : Lazy<Person>{}
The HIGHLANDER one is a bit of a joke, I think, and generally for switching between one and many it's fine to use a literal 1 – it's never going to be anything different and logically it could not be. But yes, generally, constants are good, particularly if you otherwise write a comment.
const WOTSITS_PER_THING = 13;
...
function Things(){
var wotsits = getWotsitNumberFromSomewhere();
return {things: wotsits / WOTSITS_PER_THING; leftover: wotsits % WOTSITS_PER_THING };
}... is much better than
function Things(){
var wotsits = getWotsitNumberFromSomewhere();
return {things: wotsits / 13; leftover: wotsits % 13}; // 13 wotsits per thing
}Personally, I like no comments – in an ideal world the code is clear enough. (No comments and unreadable code is really, really bad, though! Zero comments doesn't mean I like your code.) Because we're working in a fairly low level procedural language, though, you often need to comment higher level algorithms (particularly array or matrix related ones that get lost in a pile of loop code). XML header documentation is nice for the autocompletion but it is very easy for it to get out of date if you modify the code, and (like all comments) it isn't checked by the compiler. I would probably add it to the public interface at the end, given the choice (though for the projects I've released on here I was too lazy to do that).
-
The HIGHLANDER one is a bit of a joke, I think, and generally for switching between one and many it's fine to use a literal 1 – it's never going to be anything different and logically it could not be. But yes, generally, constants are good, particularly if you otherwise write a comment.
const WOTSITS_PER_THING = 13;
...
function Things(){
var wotsits = getWotsitNumberFromSomewhere();
return {things: wotsits / WOTSITS_PER_THING; leftover: wotsits % WOTSITS_PER_THING };
}... is much better than
function Things(){
var wotsits = getWotsitNumberFromSomewhere();
return {things: wotsits / 13; leftover: wotsits % 13}; // 13 wotsits per thing
}Personally, I like no comments – in an ideal world the code is clear enough. (No comments and unreadable code is really, really bad, though! Zero comments doesn't mean I like your code.) Because we're working in a fairly low level procedural language, though, you often need to comment higher level algorithms (particularly array or matrix related ones that get lost in a pile of loop code). XML header documentation is nice for the autocompletion but it is very easy for it to get out of date if you modify the code, and (like all comments) it isn't checked by the compiler. I would probably add it to the public interface at the end, given the choice (though for the projects I've released on here I was too lazy to do that).
BobJanova wrote:
Personally, I like no comments
Today I came across a piece of code again that was something like:
' Assign a value to an integer.
Dim i As Integer = 10Written by a self-proclaimed senior... That makes me really sad :(( Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS? I am sure it had a good reason way back when, but I fail to see it now :)
It's an OO world.
public class Naerling : Lazy<Person>{}
-
BobJanova wrote:
Personally, I like no comments
Today I came across a piece of code again that was something like:
' Assign a value to an integer.
Dim i As Integer = 10Written by a self-proclaimed senior... That makes me really sad :(( Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS? I am sure it had a good reason way back when, but I fail to see it now :)
It's an OO world.
public class Naerling : Lazy<Person>{}
Naerling wrote:
Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS?
Like dictators who rule with an iron fist and force policies to be their way always and forever, constants dictate that their value never changes and they YELL AT YOU to remind you of this fact!!!!
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
-
Naerling wrote:
Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS?
Like dictators who rule with an iron fist and force policies to be their way always and forever, constants dictate that their value never changes and they YELL AT YOU to remind you of this fact!!!!
Somebody in an online forum wrote:
INTJs never really joke. They make a point. The joke is just a gift wrapper.
Public Const OH_OK As Boolean = True
:laugh:
It's an OO world.
public class Naerling : Lazy<Person>{}
-
BobJanova wrote:
Personally, I like no comments
Today I came across a piece of code again that was something like:
' Assign a value to an integer.
Dim i As Integer = 10Written by a self-proclaimed senior... That makes me really sad :(( Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS? I am sure it had a good reason way back when, but I fail to see it now :)
It's an OO world.
public class Naerling : Lazy<Person>{}
Yeah, those comments just take up a line of screen space where code could be. Consts, well that's just a convention from the old C days, to clearly differentiate #defined values from normal variables (C doesn't have const declarations if I remember right). In Java or C# where underscored names are generally not used anyway, constants could arguably be lower_case_with_underscores, which is less aggressive on the eye. In my own code (when I'm not subject to convention) I usually case them normally for publicly visible members (const int ThingumyWotsit = 42;).
-
BobJanova wrote:
Personally, I like no comments
Today I came across a piece of code again that was something like:
' Assign a value to an integer.
Dim i As Integer = 10Written by a self-proclaimed senior... That makes me really sad :(( Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS? I am sure it had a good reason way back when, but I fail to see it now :)
It's an OO world.
public class Naerling : Lazy<Person>{}
Naerling wrote:
Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS?
I am sure it had a good reason way back when, but I fail to see it now :)Quite simply: Every time you see a VARIABLE_IN_CAPITOLS_AND_UNDERSCORES in the code, you simply KNOW that this is a constant and you can spare yourself the effort of trying to change it. Sure, the compiler might warn you about it, depending on your IDE - but for very long codes, you might have to look up the declaration of the variable to see it is a constant. So - Capitols, for CONSTANTS. The underscore is just there because you can't use CamelCase while using capitols only.
That seems to be a PEBKAC problem, Sir. Why don't you go and fetch a coffee while I handle the operation?
-
Naerling wrote:
Btw, what's the story with CONST_HAVING_UNDERSCORES_AND_CAPITOLS?
I am sure it had a good reason way back when, but I fail to see it now :)Quite simply: Every time you see a VARIABLE_IN_CAPITOLS_AND_UNDERSCORES in the code, you simply KNOW that this is a constant and you can spare yourself the effort of trying to change it. Sure, the compiler might warn you about it, depending on your IDE - but for very long codes, you might have to look up the declaration of the variable to see it is a constant. So - Capitols, for CONSTANTS. The underscore is just there because you can't use CamelCase while using capitols only.
That seems to be a PEBKAC problem, Sir. Why don't you go and fetch a coffee while I handle the operation?
Sounds plausible, but what about READ_ONLY_PROPERTIES? :^)
It's an OO world.
public class Naerling : Lazy<Person>{}
-
Sounds plausible, but what about READ_ONLY_PROPERTIES? :^)
It's an OO world.
public class Naerling : Lazy<Person>{}
Hmmm... I use to write that the same way I write read/write-Properties. But, hey, technically, from an using point of view, it is just like a constant: You can't write it. But it may be changing, depending on other properties.
That seems to be a PEBKAC problem, Sir. Why don't you go and fetch a coffee while I handle the operation?
-
Hmmm... I use to write that the same way I write read/write-Properties. But, hey, technically, from an using point of view, it is just like a constant: You can't write it. But it may be changing, depending on other properties.
That seems to be a PEBKAC problem, Sir. Why don't you go and fetch a coffee while I handle the operation?
witm55 wrote:
I use to write that the same way I write read/write-Properties.
So do I :laugh: Just wanted to say that it is not really very different from a Const in a usage kind of way. I think with todays tools the CAPITOLS_AND_UNDERSCORES is not necessary anymore. Visual Studio IntelliSense gives an icon saying something is a Const, it gives you text saying it is a Const, it gives the same if you hoover over it and with one "go to definition" you can see really everything you want to know about it. But from a historic point of view it is sometimes good to know why certain things are as they are :)
It's an OO world.
public class Naerling : Lazy<Person>{}
