8 ms·

Very interesting article, thanks for writing! I have but one, eh, comment: > Your code should be commented Sure.. but: > * @param {string} stringToTest -

by sundvor 10y ago

Very interesting article, thanks for writing! I have but one, eh, comment: > Your code should be commented Sure.. but: > * @param {string} stringToTest - the string to test. > // make sure we have a string. > if (typeof stringToTest !== "string") { > > function isPalindrome(stringToTest) { > ... > // if we get here, it's a palindrome > return true; Do we really need to explain that stringToTest means string to test? I for one find such low level comments almost completely redundant. I prefer strong variable naming and other ways of creating clean code to littering the code with comments that the code expresses naturally. Comments should IMHO be reserved for explaining special complexities, any particular gotchyas, etc.

danappelxx 10y ago
I agree. If a comment can be automatically generated by a computer (stringToTest -> 'the string to test' can be automatically generated), it should not be a comment at all.
billsparks 10y ago
That particular comment (the @param) is for JSDOC. It's so that one can generate documentation for the code. http://usejsdoc.org/about-getting-started.html http://usejsdoc.org/about-getting-started.html
- sundvor 10y ago
  Ah, thanks for that. I'm a Vic20 + Commodore 64 Basic -> Amiga Assembly -> ColdFusion -> C# dotNetCore person myself; mostly back end, but I'll check out JSDoc for when going down that path again next.
  - marlag 10y ago
    Interesting learning streak. I took the same route, started on Vic 20 at the age of 10, but skipped on the amiga assembly, something I suffer from on a daily basis, so good choice.
    - sundvor 10y ago
      Thanks! :) The Vic 20 at about the same age here too; assembly was great, but staying for well over a decade on ColdFusion just because there was a lot of work in it (and, comfortable) was not. I forgot to mention some PHP thrown in there, but I'm glad to have been making the transition to C# in the past year. Working with a strongly typed language is quite a revelation, and some fantastic things are happening with the language and framework these days too (dotNetCore).
  - LionessLover 10y ago
    When used in the WebStorm IDE JSDoc type comments give you type checking (if the type-inspection is enabled) and autocompletion suggestions.
- nulagrithom 10y ago
  The comment is still optional. You don't have to give @param a description. @param stringToTest would suffice. http://usejsdoc.org/tags-param.html http://usejsdoc.org/tags-param.html
deciplex 10y ago
I agree. Too many comments makes it hard to sort out which are the comments that actually provide insight to how the code works (or is supposed to) from the comments that are just bullshit the author put there so he could say he puts a lot of comments in his code.
fenomas 10y ago
Couldn't help but chuckle at this: 'use strict'; // avoid ambiguity and sloppy errors If the line that starts (or ought to start) virtually every JS file you ever write can't stand without explanation, one wonders what can!
- twblalock 10y ago
  n++; // increment n
  - bbcbasic 10y ago
    and return the original value
    - twblalock 10y ago
      ++n; // don't touch this unless you know what you are doing
      - bbcbasic 10y ago
        n = ++n; // Extra thread safety
        ry_ry 10y ago
        $.incrementNumber(n, 1); // From stack overflow
        bbcbasic 10y ago
        Confession. Have written many comments stating "copied from stackoverflow http://..." http://..."
  - hvidgaard 10y ago
    I've had students that did this. It's a real pain to read code like that, and the 2nd time they handed it in, it was an automatic fail. Comments explain assumptions, and often "the why", never "the what" unless it's obscure because of optimizations.
dclowd9901 10y ago
Right? I know developers who swear by comments and ones that swear by self describing code. You can't assume you're interviewing with one or the other.
EpicEng 10y ago
And perhaps the interviewer should have been more explicit in their requirements. I have to admit I would never think to comment whiteboard code (and my production code would not contain comments like that).
meowface 10y ago
"// throw if we didn't get a string" before a throw statement two lines away from "make sure we have a string" would annoy the hell out of me in production code.
- bobbles 10y ago
  I can see a case for it if during the next 2 years of development more code is added between 'make sure' and 'throw...' because you do not want to want to worry about refactoring comments when code gets moved...
wp1 10y ago
In a whiteboard interview, comments can/should just be said out loud to the interviewer.
bhntr3 10y ago
I came here to make the same comment (pardon the pun.) This article takes such an expert tone. But it's just opinion. For me, that comment would be a red flag. He also says to write the most efficient code possible. Then doesn't. See the comments at the end of the post. Overall, I think what this shows is that as an interviewee, the best thing you can do is try to get an idea of the interviewer's expectations as quickly as possible. People love saying here that it's not a test scenario. But it is. The interviewer has a preconceived notion of what you should and shouldn't do and you need to meet that notion. As an interviewer, recognize it's easy to think you're smarter than the other person when you already know the answer. Don't be pompous. Don't assume you know better. Try to set expectations very clearly. Try to really listen to the interviewee and understand why they're making the choices they are. Personally, I would be frustrated by this interview. I feel like this article is a thin justification of a lot of standard interview practices that don't actually work. It and his further comments take a condescending tone that makes me worry he wouldn't be open to approaches he hasn't seen. Reminds me of a time an interviewer basically gave up on an interview because I told him there were O(N) algorithms for sorting strings with a fixed alphabet. He said "Best case sorting is O(nlogn)" and I could hear in his voice that for him the interview was over. I knew what radix sort was but in the moment I couldn't actually explain or implement it without looking it up and things just went downhill from there.
- tamana 10y ago
  You might get have done better if you remembered the criterion correctly. Almost every data type used in computing is represented by non-fixed-length strings over a fixed alphabet (usually {0,1}). Radix sort is O(n) in log(dictionary size) which is only a useful bound when the data set is larger than the dictionary (this is a severe but not fatal requirement. Some datasets have many duplicate values, and anyway in practice log(n) factors in real world systems are practically constant factors: an 1log(n) algorithm will be slower than a 100(1) algorithm.) You can misstate a theorem, or forget the proof, OK, but doing both is poor form.
  - bhntr3 10y ago
    You're right. I misstated it here and was clearly lying when I said I understood it. Another good tip for interviewees: If you don't really understand something well enough to explain it, sometimes it's better not to bring it up than to introduce it and look silly. Sucks. But you're more likely to lose points than gain them for just kind of knowing something exists. Also applies to hacker news comments ;)
pc86 10y ago
Comments should explain the why of code, not the what or how. From a technical standpoint you should read uncommented code and more often than not be able to tell exactly what it does (barring a lot of poorly named methods or similar architectural issues). Any comments should simply explain the business rules or decisions that led to that code. Maybe you are knowingly violating a best practice for your framework or language because following it would break business logic down the pipeline or something. This is the perfect time for a comment explaining that so a well-meaning junior developer doesn't refactor it six months from now.
deleted 10y ago
[deleted]

by sundvor 10y ago

danappelxx 10y ago

I agree. If a comment can be automatically generated by a computer (stringToTest -> 'the string to test' can be automatically generated), it should not be a comment at all.

billsparks 10y ago

That particular comment (the @param) is for JSDOC. It's so that one can generate documentation for the code. http://usejsdoc.org/about-getting-started.html http://usejsdoc.org/about-getting-started.html

sundvor 10y ago
Ah, thanks for that. I'm a Vic20 + Commodore 64 Basic -> Amiga Assembly -> ColdFusion -> C# dotNetCore person myself; mostly back end, but I'll check out JSDoc for when going down that path again next.
- marlag 10y ago
  Interesting learning streak. I took the same route, started on Vic 20 at the age of 10, but skipped on the amiga assembly, something I suffer from on a daily basis, so good choice.
  - sundvor 10y ago
    Thanks! :) The Vic 20 at about the same age here too; assembly was great, but staying for well over a decade on ColdFusion just because there was a lot of work in it (and, comfortable) was not. I forgot to mention some PHP thrown in there, but I'm glad to have been making the transition to C# in the past year. Working with a strongly typed language is quite a revelation, and some fantastic things are happening with the language and framework these days too (dotNetCore).
- LionessLover 10y ago
  When used in the WebStorm IDE JSDoc type comments give you type checking (if the type-inspection is enabled) and autocompletion suggestions.
nulagrithom 10y ago
The comment is still optional. You don't have to give @param a description. @param stringToTest would suffice. http://usejsdoc.org/tags-param.html http://usejsdoc.org/tags-param.html

deciplex 10y ago

I agree. Too many comments makes it hard to sort out which are the comments that actually provide insight to how the code works (or is supposed to) from the comments that are just bullshit the author put there so he could say he puts a lot of comments in his code.

fenomas 10y ago

Couldn't help but chuckle at this: 'use strict'; // avoid ambiguity and sloppy errors If the line that starts (or ought to start) virtually every JS file you ever write can't stand without explanation, one wonders what can!

twblalock 10y ago
n++; // increment n
- bbcbasic 10y ago
  and return the original value
  - twblalock 10y ago
    ++n; // don't touch this unless you know what you are doing
    - bbcbasic 10y ago
      n = ++n; // Extra thread safety
      - ry_ry 10y ago
        $.incrementNumber(n, 1); // From stack overflow
        bbcbasic 10y ago
        Confession. Have written many comments stating "copied from stackoverflow http://..." http://..."
- hvidgaard 10y ago
  I've had students that did this. It's a real pain to read code like that, and the 2nd time they handed it in, it was an automatic fail. Comments explain assumptions, and often "the why", never "the what" unless it's obscure because of optimizations.

dclowd9901 10y ago

Right? I know developers who swear by comments and ones that swear by self describing code. You can't assume you're interviewing with one or the other.

EpicEng 10y ago

And perhaps the interviewer should have been more explicit in their requirements. I have to admit I would never think to comment whiteboard code (and my production code would not contain comments like that).

meowface 10y ago

"// throw if we didn't get a string" before a throw statement two lines away from "make sure we have a string" would annoy the hell out of me in production code.

bobbles 10y ago
I can see a case for it if during the next 2 years of development more code is added between 'make sure' and 'throw...' because you do not want to want to worry about refactoring comments when code gets moved...

wp1 10y ago

In a whiteboard interview, comments can/should just be said out loud to the interviewer.

bhntr3 10y ago

I came here to make the same comment (pardon the pun.) This article takes such an expert tone. But it's just opinion. For me, that comment would be a red flag. He also says to write the most efficient code possible. Then doesn't. See the comments at the end of the post. Overall, I think what this shows is that as an interviewee, the best thing you can do is try to get an idea of the interviewer's expectations as quickly as possible. People love saying here that it's not a test scenario. But it is. The interviewer has a preconceived notion of what you should and shouldn't do and you need to meet that notion. As an interviewer, recognize it's easy to think you're smarter than the other person when you already know the answer. Don't be pompous. Don't assume you know better. Try to set expectations very clearly. Try to really listen to the interviewee and understand why they're making the choices they are. Personally, I would be frustrated by this interview. I feel like this article is a thin justification of a lot of standard interview practices that don't actually work. It and his further comments take a condescending tone that makes me worry he wouldn't be open to approaches he hasn't seen. Reminds me of a time an interviewer basically gave up on an interview because I told him there were O(N) algorithms for sorting strings with a fixed alphabet. He said "Best case sorting is O(nlogn)" and I could hear in his voice that for him the interview was over. I knew what radix sort was but in the moment I couldn't actually explain or implement it without looking it up and things just went downhill from there.

tamana 10y ago
You might get have done better if you remembered the criterion correctly. Almost every data type used in computing is represented by non-fixed-length strings over a fixed alphabet (usually {0,1}). Radix sort is O(n) in log(dictionary size) which is only a useful bound when the data set is larger than the dictionary (this is a severe but not fatal requirement. Some datasets have many duplicate values, and anyway in practice log(n) factors in real world systems are practically constant factors: an 1log(n) algorithm will be slower than a 100(1) algorithm.) You can misstate a theorem, or forget the proof, OK, but doing both is poor form.
- bhntr3 10y ago
  You're right. I misstated it here and was clearly lying when I said I understood it. Another good tip for interviewees: If you don't really understand something well enough to explain it, sometimes it's better not to bring it up than to introduce it and look silly. Sucks. But you're more likely to lose points than gain them for just kind of knowing something exists. Also applies to hacker news comments ;)

pc86 10y ago

Comments should explain the why of code, not the what or how. From a technical standpoint you should read uncommented code and more often than not be able to tell exactly what it does (barring a lot of poorly named methods or similar architectural issues). Any comments should simply explain the business rules or decisions that led to that code. Maybe you are knowingly violating a best practice for your framework or language because following it would break business logic down the pipeline or something. This is the perfect time for a comment explaining that so a well-meaning junior developer doesn't refactor it six months from now.

deleted 10y ago

[deleted]