Hacker News Reader

Comment by nonethewiser | Hacker News Reader

It's interesting to see just about every line in the code commented. Makes you re-examine the assumptions made when people say "the code should be self documenting."

Namely, that the code will be read by someone who knows the language. And arguably that the code should be capable of being "self-documenting." Although perhaps people well-versed in COBOL would argue COBOL can be, and I just don't know it.

View on HN

See commit d9a5e3e, “Added comments to the code to help curious folks understand what each line is doing”.

yep. the comments are for folks who have never tried to read cobol before, which is probably 99% of people looking at the project. this way they can understand a familiar idea expressed in a language that is probably wildly different from what theyre used to.

for example IT IS YELLING AT US THE WHOLE TIME

I seem to understand most of it except for this data typing stuff:

    PIC 9(9)V99

and the like. What is PIC?

IIRC is means a pictorial definition of a value so the above is a float printable using 12 positions which for maximum value would be as 999999999.99 While a PIC X(10) Means character string length 10. It was defined in era of fixed width fonts and band printers so the max printing width was 132 and one had to know exactly where each character would print. Report writing in COBOL is easy.

Almost correct. However, this is not a float but a fixed decimal value with two decimals. The V is not stored but just used to indicate where the decimal sign should be. Source: I've written a lot of COBOL years ago.

PIC is short for PICTURE, which was the original form of the keyword. Picture the number printed this way.

Edit: the numbers in parentheses are repeats. PIC 9(9) means up to 9 digits in the printed representation of the value stored in the variable that has this PIC.

I heard people at a bank claim that COBOL code is basically natural language and thus self-documenting. I almost laughed out at that.

Bank teller: "And how can I help you?"

Customer: "PERFORM 500-DEDUCT-ACCOUNT-BALANCE"

Bank teller: "Ok, great, and how much?"

Customer:

"01 TRANSACTION RECORD

  05 TRANSACTION-AMOUNT PIC 9(9)V99

MOVE 100.00 TO TRANSACTION-AMOUNT"

A future we didn't quite make it into.

"Namely, that the code will be read by someone who knows the language. " Most of the time I think it depends on the context. If you're writing code as a learning exercise, either for yourself or for others, it makes sense to use comments to expand on what lines actually do.

If you're in the context of a professional environment, where you chose the team, it makes sense to be more dogmatic about it to enforce a better overall architecture, and you can safely assume that the next reader at least knows the language already.

Reply on news.ycombinator.com