Do you Program in Paragraphs or Sentences?
-
This was inspired by Marc Clifton's post [Dumbing down code so it can be maintained by junior devs](https://www.codeproject.com/Lounge.aspx?fid=1159&fr=126#xx0xx) I'm a horizontal programmer. I write chainable methods with (short) descriptive names. The top of my methods usually consists of a few "sentences" composed of these "words". If I can put my code on one line, (braces, etc.) I usually do. Eg, simple method:
// Not me
string Foo(int x)
{
if(x == 1)
{
return "one";
}
else
{
return "not one";
}
}
}// sometimes me
string Foo(int x){
if (x == 1) {
return "one";
} else {
return "not one";
}
}// usually me
string Foo(int x) => (x == 1) ? "one" : "not one";// often me
string Foo(this int x) => (x == 1) ? "one" : "not one";I do things like this. (Not really this weird though :)).
public static List WhenNotEmpty(this List item) => (item.Count > 0) ? item : null;
public static string Prepare(this string item, out string prepared) => ((prepared = item + "Appended") == "HelloAppended") ? "ok" : null ;
public static void Manipulate(this string item, string stuff) => Debug.WriteLine($"{item}:{stuff}");So I can write in sentences
var list = new List {"a", "Hello", "c"};
list.WhenNotEmpty()?.ForEach(s => s.Prepare(out var r)?.Manipulate(r));
Instead of paragraphs. (something like (methods would be a little different))
var list = new List {"a", "Hello", "c"};
if(list.count > 0){
foreach(var i in list){
var (condition, temp) = Prepare(i);
if(condition != null){
Manipulate(temp);
}
}
}Getting to the point, (finally :zzz: ) The paragraphs approach is clearer at the micro level (the details are clear), but the sentences is clearer at the macro level (the overall intent is clear). Of course you can wrap this paragraph in a method. But when you don't: Do you tend to write more at the macro/sentence level or micro/paragraph level?
Paragraph level. Are you thinking that the compiler does something more optimized because you wrote it as a sentence instead of paragraph? Or were you thinking that less typing benefits the project overall? Or perhaps some other underlying reason? Paragraph style is not only more readable and understandable to another programmer reading it for the first time, it is more readable and understandable to you 6 months, a year, or 2 years later when you revisit the code for the first time since you finished it. Paragraph style is also easier to debug and see runtime values. When you are not the only programmer involved now or conceivably in the future, paragraph style would have a positive effect on the maintenance portion of lifecycle cost. Another benefit of paragraph style is that it lends itself better to adding comments that explain the what and why of what you are doing.
-
Check out [Extension Methods (C# Programming Guide) | Microsoft Docs](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/extension-methods)
Thanks, I think. ;-}
-
This was inspired by Marc Clifton's post [Dumbing down code so it can be maintained by junior devs](https://www.codeproject.com/Lounge.aspx?fid=1159&fr=126#xx0xx) I'm a horizontal programmer. I write chainable methods with (short) descriptive names. The top of my methods usually consists of a few "sentences" composed of these "words". If I can put my code on one line, (braces, etc.) I usually do. Eg, simple method:
// Not me
string Foo(int x)
{
if(x == 1)
{
return "one";
}
else
{
return "not one";
}
}
}// sometimes me
string Foo(int x){
if (x == 1) {
return "one";
} else {
return "not one";
}
}// usually me
string Foo(int x) => (x == 1) ? "one" : "not one";// often me
string Foo(this int x) => (x == 1) ? "one" : "not one";I do things like this. (Not really this weird though :)).
public static List WhenNotEmpty(this List item) => (item.Count > 0) ? item : null;
public static string Prepare(this string item, out string prepared) => ((prepared = item + "Appended") == "HelloAppended") ? "ok" : null ;
public static void Manipulate(this string item, string stuff) => Debug.WriteLine($"{item}:{stuff}");So I can write in sentences
var list = new List {"a", "Hello", "c"};
list.WhenNotEmpty()?.ForEach(s => s.Prepare(out var r)?.Manipulate(r));
Instead of paragraphs. (something like (methods would be a little different))
var list = new List {"a", "Hello", "c"};
if(list.count > 0){
foreach(var i in list){
var (condition, temp) = Prepare(i);
if(condition != null){
Manipulate(temp);
}
}
}Getting to the point, (finally :zzz: ) The paragraphs approach is clearer at the micro level (the details are clear), but the sentences is clearer at the macro level (the overall intent is clear). Of course you can wrap this paragraph in a method. But when you don't: Do you tend to write more at the macro/sentence level or micro/paragraph level?
In our world, and our code reviews, this one line stuff has to go. The coding standards should dictate the formatting. BUT: The Situation can dictate exceptions. We have defensible and in-defensible deviations. Blocks of similar code where reading one line is effectively the same in the block, we allow the one line to create a "tabular" view of what is transpiring. BTW, I don't consider breaking down the code into properly formatted statements to be dumbing down the code. I also think that different companies CAN AND SHOULD have different coding standards! But overall, I believe if you can pick up a piece of code, and not know if YOU wrote it, or someone else on your team wrote it... Then you are cooking with gas.
-
This was inspired by Marc Clifton's post [Dumbing down code so it can be maintained by junior devs](https://www.codeproject.com/Lounge.aspx?fid=1159&fr=126#xx0xx) I'm a horizontal programmer. I write chainable methods with (short) descriptive names. The top of my methods usually consists of a few "sentences" composed of these "words". If I can put my code on one line, (braces, etc.) I usually do. Eg, simple method:
// Not me
string Foo(int x)
{
if(x == 1)
{
return "one";
}
else
{
return "not one";
}
}
}// sometimes me
string Foo(int x){
if (x == 1) {
return "one";
} else {
return "not one";
}
}// usually me
string Foo(int x) => (x == 1) ? "one" : "not one";// often me
string Foo(this int x) => (x == 1) ? "one" : "not one";I do things like this. (Not really this weird though :)).
public static List WhenNotEmpty(this List item) => (item.Count > 0) ? item : null;
public static string Prepare(this string item, out string prepared) => ((prepared = item + "Appended") == "HelloAppended") ? "ok" : null ;
public static void Manipulate(this string item, string stuff) => Debug.WriteLine($"{item}:{stuff}");So I can write in sentences
var list = new List {"a", "Hello", "c"};
list.WhenNotEmpty()?.ForEach(s => s.Prepare(out var r)?.Manipulate(r));
Instead of paragraphs. (something like (methods would be a little different))
var list = new List {"a", "Hello", "c"};
if(list.count > 0){
foreach(var i in list){
var (condition, temp) = Prepare(i);
if(condition != null){
Manipulate(temp);
}
}
}Getting to the point, (finally :zzz: ) The paragraphs approach is clearer at the micro level (the details are clear), but the sentences is clearer at the macro level (the overall intent is clear). Of course you can wrap this paragraph in a method. But when you don't: Do you tend to write more at the macro/sentence level or micro/paragraph level?
Quote:
string Foo(int x){ if (x == 1) { return "one"; } else { return "not one"; } }
string Foo(int x) { return x == 1 ? "one" : "not one"; }
(I also tend to twitch when I see a "return" followed by an "else".)
"(I) am amazed to see myself here rather than there ... now rather than then". ― Blaise Pascal
-
Paragraph level. Are you thinking that the compiler does something more optimized because you wrote it as a sentence instead of paragraph? Or were you thinking that less typing benefits the project overall? Or perhaps some other underlying reason? Paragraph style is not only more readable and understandable to another programmer reading it for the first time, it is more readable and understandable to you 6 months, a year, or 2 years later when you revisit the code for the first time since you finished it. Paragraph style is also easier to debug and see runtime values. When you are not the only programmer involved now or conceivably in the future, paragraph style would have a positive effect on the maintenance portion of lifecycle cost. Another benefit of paragraph style is that it lends itself better to adding comments that explain the what and why of what you are doing.
When I started I was actually thinking more about separating concepts and mechanics, or maybe better, business vs technology. But I think I lost that some when playing with creating my examples. ) In business applications (vs scientific/engineering) most methods implement some part of a business function. At an absurdum extreme you could write the application in one procedural block with thousands of lines of branching/conditional code, where each line does no more than a single thing. It contains an atomic concept. So, you wouldn't write `if(x == 1 || x == 3)`, that is two concepts. At this extreme, every atomic thought is crystal clear, but the big-picture of what the method does becomes a forest-trees thing. We decompose software into logical, understandably named chunks, like methods and classes. At another absurd extreme, we could make each concept a method - `bool IsValueEqualToOne(int x) {if x ==1 return true else return false}`. This is just as bad. We have only translated from a technical representation `(x == 1)?` to a business representation `IsValueEqualToOne`. In real-world programming we balance the size and form of our chunks. In some cases, it is better to combine at a "technical" level - `if(x == 1 || x == 3)`. In others, a business level is better
// transfer
if(AccountHasFunds(sourceAccount, amount)){
debit(sourceAccount, amount);
credit(targetAccount amount);
}At the opposite extreme or "can't see the forest for the trees" is "needle in a haystack", one liners. Like the examples I gave. ( and tried to disclaim as how I would actually do it. :) ) So, to your question
Quote:
compiler does something more optimized... Or perhaps some other underlying reason?
In rereading it sounds like I may be advocating "one-liners", but not really. All the LINQ and stuff has a greater chance of compiler confusion than optimization. Maybe the best I can think of is that each method we write contains a business purpose and a technical implementation. The clearest code communicates both, and the best code does this in a maintainable way. With LINQ style and functional becoming popular I was curious to see if people were writing more that way. My preferred method of coding combines approaches, made easier with local functions. (I just make up "transaction syntax for simplicity)
void TransferFunds(source, target, amount){
// Business - more compressed to highlight business logic
if(AccountHasF -
Quote:
string Foo(int x){ if (x == 1) { return "one"; } else { return "not one"; } }
string Foo(int x) { return x == 1 ? "one" : "not one"; }
(I also tend to twitch when I see a "return" followed by an "else".)
"(I) am amazed to see myself here rather than there ... now rather than then". ― Blaise Pascal
I've seen a lot of discussion lately about single point of exit vs multiple points of exit. Since my IDE makes them easy to spot I've started using multiples more in `if` and `switch`. But when I see the code in a plain text editor it still can look a little confusing.
-
I've seen a lot of discussion lately about single point of exit vs multiple points of exit. Since my IDE makes them easy to spot I've started using multiples more in `if` and `switch`. But when I see the code in a plain text editor it still can look a little confusing.
I have no issue with "multiple exits"; when used to avoid lengthy "if ... else". The point is, the "else" in "if ... return else" is totally redunant. And sometimes, it's "clearer" to simply return with a simple "if NOT ... return" instead of a lengthy "positive" if. But "if NOT's" can get confusing if misused.
"(I) am amazed to see myself here rather than there ... now rather than then". ― Blaise Pascal
-
Paragraphs, then collapse all the functions I'm not actively messing around with.
We won't sit down. We won't shut up. We won't go quietly away. YouTube, VidMe and My Mu[sic], Films and Windows Programs, etc. and FB
If you use VS, you can change the formatting parameters depending on who you show the code to: Before showing your code to a code homeopath, you check every single option in the New Lines and Spacing sections and uncheck the Wrapping options. Then go to the closing brace of the file, delete and retype it, and the code is ready for presentation. When you go back to the coding, you set the switches back to your preferences, delete and retype the closing brace. If you are fond of end-of-line comments, they won't be nicely lined up at column 70 when you show your code in diluted mode. That is usually a minor problem with the homeopaths; the never look beyond column 30 of the source file anyway. Besides, the majority of them are totally unfamiliar with the very concept of end-of-line comments; they put all comments into the huge commment block over every function. This works fine with C#; I never tried with other languages. In the old days before we had automatic formatting, and code discussions were based on hardcopy printouts, a nice trick was to print all source code double spaced. I have had homeopaths commenting point to a few specific blank lines telling that I could drop the blank to emphasize that they really go together - never noticing that the entire file had "blank lines" between every printed line - or three or five blank lines.
-
I have no issue with "multiple exits"; when used to avoid lengthy "if ... else". The point is, the "else" in "if ... return else" is totally redunant. And sometimes, it's "clearer" to simply return with a simple "if NOT ... return" instead of a lengthy "positive" if. But "if NOT's" can get confusing if misused.
"(I) am amazed to see myself here rather than there ... now rather than then". ― Blaise Pascal
Got it. See what you are saying.
-
Got it. See what you are saying.
-
I can parse it line by line at a normal reading speed. Takes about 3-4 seconds the first time I see it. The initial style I can parse and verify without having to read a single word. Takes me about 250 milliseconds. The benefit of having spacious functions is that mistakes become embarrassingly easy to spot. Likewise, properly written functions become very easy to parse, because they look so damn familiar. I find "less lines of code" a dubious benefit. A cramped style is more time-consuming to debug, both in terms of setting breakpoints and retracing logged exceptions. Also, I definitely agree functions should not grow too big.. but stacking multiple logical steps on a single line only gives you the illusion of small functions. I say: be spacious, let functions grow, and flag them for refactoring if they don't fit on a single page. The point is to write code that's self-evident +6 months in the future. Quick to read, amend and fix if need be.
KBZX5000 wrote:
because they look so damn familiar.
That is the main point here. "Readability" is not as rationally and objectively defined as we would like to think; it is highly personal. What you learned at school. Universities (at least here in Norway) tend to stress whitespace as the most essential element of good programming, so yuong programmers thend to frown at lines exceeding 30 characters. When the code is spread over three times as many lines, I spend a lot of attention searching for the match: Hey, there is an "else" here - where was the matching "if"? Not on the line above, not two or three lines above, but four lines above. if/else is usually fairly simple to handle, though. Braces are far worse. When you unroll seven levels of nested blocks, exactly where is the start of the block closed by the fourth one in the unstacking? You don't know which keyword to look for; everything starts with a brace. If the match is 16 lines higher up, it is much easier to match than if it is 67 lines higher up! Also, I avoid superflous braces: There is no reason to make a block for every single-statement if, while or for clause. If you try to find the matching opening brace (like above), it is far easier if there are five candidates, as compared to twenty three. (Exceptions are exceptions: The language "designers" did not learn from Pascal that a statement IS a block; they defined a block concept excluding a statement from being a block. Then came the excptional people declaring the exception mechanism to require blocks for all its parts. I consider statements not being blocks as one of the very big mistakes in the formal definition of the c language.) It is not just for the braces: I really dislike "the rightward migration of source code", as it was once described. To some people, ideal source code has a left margin like a funnel (and sometimes, the underside of the funnel makes you think that you are programming lisp). Matching opening and closing braces is close to impossible except for the two or three innermost levels. The fewer indentation levels, the better! Following a "return" statement by an "else" is meaningless. I kept it the code example above, because I know lot of coders would bark if I removed it, even though it really has no meaning, and is in a sense misleading: It seems to suggest that the code following the if(){} else{} is unconditional, regardless of the if-outcome. You actual
-
When I started I was actually thinking more about separating concepts and mechanics, or maybe better, business vs technology. But I think I lost that some when playing with creating my examples. ) In business applications (vs scientific/engineering) most methods implement some part of a business function. At an absurdum extreme you could write the application in one procedural block with thousands of lines of branching/conditional code, where each line does no more than a single thing. It contains an atomic concept. So, you wouldn't write `if(x == 1 || x == 3)`, that is two concepts. At this extreme, every atomic thought is crystal clear, but the big-picture of what the method does becomes a forest-trees thing. We decompose software into logical, understandably named chunks, like methods and classes. At another absurd extreme, we could make each concept a method - `bool IsValueEqualToOne(int x) {if x ==1 return true else return false}`. This is just as bad. We have only translated from a technical representation `(x == 1)?` to a business representation `IsValueEqualToOne`. In real-world programming we balance the size and form of our chunks. In some cases, it is better to combine at a "technical" level - `if(x == 1 || x == 3)`. In others, a business level is better
// transfer
if(AccountHasFunds(sourceAccount, amount)){
debit(sourceAccount, amount);
credit(targetAccount amount);
}At the opposite extreme or "can't see the forest for the trees" is "needle in a haystack", one liners. Like the examples I gave. ( and tried to disclaim as how I would actually do it. :) ) So, to your question
Quote:
compiler does something more optimized... Or perhaps some other underlying reason?
In rereading it sounds like I may be advocating "one-liners", but not really. All the LINQ and stuff has a greater chance of compiler confusion than optimization. Maybe the best I can think of is that each method we write contains a business purpose and a technical implementation. The clearest code communicates both, and the best code does this in a maintainable way. With LINQ style and functional becoming popular I was curious to see if people were writing more that way. My preferred method of coding combines approaches, made easier with local functions. (I just make up "transaction syntax for simplicity)
void TransferFunds(source, target, amount){
// Business - more compressed to highlight business logic
if(AccountHasFIn my first university level programming course (I had been fiddeling a little around before that), the professor provided one guideline that I still think is great: A program should fit in a single page. Usually, it will be more than half a page, but never more than that. ("One page" was understood to be 60 code lines.) You can't solve the program in 60 lines of Pascal, you say? OK, so make up another programming language in which you can solve the problem in 60 lines. Say, if an essential part of your solution is to sort a table of records backwards on the surname field, according to Swedish alphabetic sorting, then pretend that you have a language in which "sorting a table backwards on the surname field according to Swedish sorting rules" is a language primitive. When you have made a clean, readable solution in this hypothetical language, you go ahead to make another program by the same basic rules: One for doing that sorting... I think this is a very good philosophical approach to code modularization: Make yourself a language that lets you solve the problem in 30-60 lines. Less than 30 lines provides so little detail that it is useless (like "void main(void) {solvetheproblem();}"). Make sure that the way the problem is solved is visible in the code! But don't bring in too many details; requiring more than 60 distinct operations (aka. code lines) indicates that you did not use the right language for the task. So make yourself a better suited language. Obviously, these are main rules, not absolute. Some problems require less than 30 lines, and in any production setting you cannot expect library functions to suit your problem ideally, adding red tape. But as a way of thinking, it is a great approach: Every level of your code should add a significant, but not an excessive amount of detail. And, relate that stepwise detailing to the problem at hand, not to the libraries you use, language or other coding elements. Even today I think this lesson, in my very first year of study to become a programmer, is one of the most valuable ones I has throughout my studies.
-
I've seen a lot of discussion lately about single point of exit vs multiple points of exit. Since my IDE makes them easy to spot I've started using multiples more in `if` and `switch`. But when I see the code in a plain text editor it still can look a little confusing.
I frequently use multiple exits, to simplify the code structure, reducing nesting levels. However, the last bug I fixed in one program that is my responsibility was related to this: A few months ago, I added a "try / catch / finally" to improve error handling. Within that "try" was an age old "return" for a rather curious case, hit only if the PC did not have a sufficiently updatet dotNet (and since updates are pushed from a central deployment server, this only happens if you plug in a portable that is not yet detected by the deployment server). Before the "return" was executed, the "finally" block was processed, which was certainly not appropriate in that situation. I will certainly not stop sprinkling my code with return statements, but I have learned a lesson about paying attention to finally-clauses.
-
This was inspired by Marc Clifton's post [Dumbing down code so it can be maintained by junior devs](https://www.codeproject.com/Lounge.aspx?fid=1159&fr=126#xx0xx) I'm a horizontal programmer. I write chainable methods with (short) descriptive names. The top of my methods usually consists of a few "sentences" composed of these "words". If I can put my code on one line, (braces, etc.) I usually do. Eg, simple method:
// Not me
string Foo(int x)
{
if(x == 1)
{
return "one";
}
else
{
return "not one";
}
}
}// sometimes me
string Foo(int x){
if (x == 1) {
return "one";
} else {
return "not one";
}
}// usually me
string Foo(int x) => (x == 1) ? "one" : "not one";// often me
string Foo(this int x) => (x == 1) ? "one" : "not one";I do things like this. (Not really this weird though :)).
public static List WhenNotEmpty(this List item) => (item.Count > 0) ? item : null;
public static string Prepare(this string item, out string prepared) => ((prepared = item + "Appended") == "HelloAppended") ? "ok" : null ;
public static void Manipulate(this string item, string stuff) => Debug.WriteLine($"{item}:{stuff}");So I can write in sentences
var list = new List {"a", "Hello", "c"};
list.WhenNotEmpty()?.ForEach(s => s.Prepare(out var r)?.Manipulate(r));
Instead of paragraphs. (something like (methods would be a little different))
var list = new List {"a", "Hello", "c"};
if(list.count > 0){
foreach(var i in list){
var (condition, temp) = Prepare(i);
if(condition != null){
Manipulate(temp);
}
}
}Getting to the point, (finally :zzz: ) The paragraphs approach is clearer at the micro level (the details are clear), but the sentences is clearer at the macro level (the overall intent is clear). Of course you can wrap this paragraph in a method. But when you don't: Do you tend to write more at the macro/sentence level or micro/paragraph level?
If God wanted us to program in sentences, He would have abolished all languages except APL. :laugh: