7 ms·

I found this technique to work quite well, but this idea does not mean imply that one should simply "quit writing comments", but rather that comments can most o

by cessor 8y ago

I found this technique to work quite well, but this idea does not mean imply that one should simply "quit writing comments", but rather that comments can most often be replaced with actual structures that improve the code (e.g., extracting long boolean expressions into a function with the same name as the actual comment), but that also depends on the language and aptitude of the developer. Would you really argue in favor of something like this? ``` class Account { ... /// returns the accountId public int d_nr() { ... } } ``` ``` class Account { ... /// returns the accountId public int getAccountId () { ... } } ``` The first comment is obsolete when using a proper method name, the second does that and so the comment is redundant. May I ask: What did you experience in the wild?

scarface74 8y ago
Or even better don’t return an int return an “accountId” type.
- jokerx 8y ago
  Please don't do this! All you have accomplished really is to move the descriptive name from the variable's name to the variable's type, and at what cost? You now have to create a whole new datatype. The programmer must look up that datatype and see oh, it's just an int. And now you need conversion routines or worse yet casting to convert that type to a simple int for interop reasons (database, UI). Experience has shown that it is very productive to have a small number of generally useful datatypes which are augmented by custom datatypes. Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. (It's especially unwarranted for a variable that is an immutable variable serving as a simple id.)
  - scarface74 8y ago
    You haven’t just moved the descriptive name from the variable name to the type. If you are using a strongly typed language, you can just right click on the accountId type and find everywhere in your codebase where the “accountId” is being used. The “accountId” is not “just an int”. An accountId has semantics that would be different than an int. An accountId is not the same as a “customerId” that may also be represented as an int. The accountId also has different uses than an int. You’re not going to take the sum, average, etc of an accountId. An accountId that happens to have a value of 1 is semantically not equivalent of a customerId of 1. A method that expects a list of accountIds that are just ints will just as happily take a list of customerIds. But a method that takes as a parameter List<AccountId> will cause a compile time error if you pass in a List<CustomerId>. Why use a strongly typed language and then ruin one of the benefits of it if you don’t use domain specific types?
    - cessor 8y ago
      I agree with @scarface74 and would go even further in that I would probably create a custom type for List<AccountId> to convey the purpose of what that thing is now. And as for the "type shyness": > Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. It is never "just an int". Soon you will ask questions about the int, and in a sufficiently large application you will forget the answers to the quesions easily, and scatter the same question (i.e., the same boolean logic) all over the place. Consider an application where you need to filter something by year. A year, you know? As in 1974, 2018, etc. An int is bad, because an int could be -5, which does not make sense. Ok, a uint then? Still bad, because then there is a year 0 and - if your application deals with birthdays of real people, 1800 would be an invalid birthday. The semantics (or pragmatics, linguistically speaking) emerge from how you interpret the integer, and this interpretation can happily live in that one file with that one class that encapsulates "just" that integer. The AccountId probably shouldn't be < 0, and a specific type could be the one place where you make sure that this is always the case. What if you start with a 32bit integer and suddenly you realize that your weird Internet-Of-Things-Sensor reading database has grown and the 32bit integer is getting too small? You could just use 64bits. With "just an int", you now get to change every single function that expects an int for the purpose of a SensorReadingId (or an account id or whatever) and change it to size_t, uint, int64 or whatever. OR, you just tell the object that its internal representation uses 64bits now, because the AccountId class is the one single place that deals with account ids. The type provides a consistent interface that allows you to infer the semantics of its use. An int doesn't do that. This idea predates java by some ~20 years [1]. An int is not an account id. An int is not a year. An email is not a string. The result of working like that is considered a code smell [2]. Still, coming back to the example I made: It was primarily about commenting. I was taught to always comment, and StyleCop enforced comments on each and every field of a class, leading to noisy, superfluous comments. /// Gets or Sets the Name string Name { get; set; } does not add anything. As for returning an AccountID: I'd like to point out that the Account is a strong and independent object, who can make his own decisions and does not need to return anything. Returning its id like that is actually breaking encapsulation. Still if you do it, it probably shouldn't be an integer. Why are people scared of creating types and objects? [1] https://link.springer.com/chapter/10.1007%2F978-1-4612-6315-9_22 https://link.springer.com/chapter/10.1007%2F978-1-4612-6315-... [2] https://sourcemaking.com/refactoring/smells/primitive-obsession https://sourcemaking.com/refactoring/smells/primitive-obsess...

by cessor 8y ago

scarface74 8y ago

Or even better don’t return an int return an “accountId” type.

jokerx 8y ago
Please don't do this! All you have accomplished really is to move the descriptive name from the variable's name to the variable's type, and at what cost? You now have to create a whole new datatype. The programmer must look up that datatype and see oh, it's just an int. And now you need conversion routines or worse yet casting to convert that type to a simple int for interop reasons (database, UI). Experience has shown that it is very productive to have a small number of generally useful datatypes which are augmented by custom datatypes. Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. (It's especially unwarranted for a variable that is an immutable variable serving as a simple id.)
- scarface74 8y ago
  You haven’t just moved the descriptive name from the variable name to the type. If you are using a strongly typed language, you can just right click on the accountId type and find everywhere in your codebase where the “accountId” is being used. The “accountId” is not “just an int”. An accountId has semantics that would be different than an int. An accountId is not the same as a “customerId” that may also be represented as an int. The accountId also has different uses than an int. You’re not going to take the sum, average, etc of an accountId. An accountId that happens to have a value of 1 is semantically not equivalent of a customerId of 1. A method that expects a list of accountIds that are just ints will just as happily take a list of customerIds. But a method that takes as a parameter List<AccountId> will cause a compile time error if you pass in a List<CustomerId>. Why use a strongly typed language and then ruin one of the benefits of it if you don’t use domain specific types?
  - cessor 8y ago
    I agree with @scarface74 and would go even further in that I would probably create a custom type for List<AccountId> to convey the purpose of what that thing is now. And as for the "type shyness": > Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. It is never "just an int". Soon you will ask questions about the int, and in a sufficiently large application you will forget the answers to the quesions easily, and scatter the same question (i.e., the same boolean logic) all over the place. Consider an application where you need to filter something by year. A year, you know? As in 1974, 2018, etc. An int is bad, because an int could be -5, which does not make sense. Ok, a uint then? Still bad, because then there is a year 0 and - if your application deals with birthdays of real people, 1800 would be an invalid birthday. The semantics (or pragmatics, linguistically speaking) emerge from how you interpret the integer, and this interpretation can happily live in that one file with that one class that encapsulates "just" that integer. The AccountId probably shouldn't be < 0, and a specific type could be the one place where you make sure that this is always the case. What if you start with a 32bit integer and suddenly you realize that your weird Internet-Of-Things-Sensor reading database has grown and the 32bit integer is getting too small? You could just use 64bits. With "just an int", you now get to change every single function that expects an int for the purpose of a SensorReadingId (or an account id or whatever) and change it to size_t, uint, int64 or whatever. OR, you just tell the object that its internal representation uses 64bits now, because the AccountId class is the one single place that deals with account ids. The type provides a consistent interface that allows you to infer the semantics of its use. An int doesn't do that. This idea predates java by some ~20 years [1]. An int is not an account id. An int is not a year. An email is not a string. The result of working like that is considered a code smell [2]. Still, coming back to the example I made: It was primarily about commenting. I was taught to always comment, and StyleCop enforced comments on each and every field of a class, leading to noisy, superfluous comments. /// Gets or Sets the Name string Name { get; set; } does not add anything. As for returning an AccountID: I'd like to point out that the Account is a strong and independent object, who can make his own decisions and does not need to return anything. Returning its id like that is actually breaking encapsulation. Still if you do it, it probably shouldn't be an integer. Why are people scared of creating types and objects? [1] https://link.springer.com/chapter/10.1007%2F978-1-4612-6315-9_22 https://link.springer.com/chapter/10.1007%2F978-1-4612-6315-... [2] https://sourcemaking.com/refactoring/smells/primitive-obsession https://sourcemaking.com/refactoring/smells/primitive-obsess...