3 ms·

If you expect the people reviewing it to be developers: 1) Tell me how to run it locally (docker is a good idea, if relevant) and where the code's entry point

by ashark 9y ago

If you expect the people reviewing it to be developers: 1) Tell me how to run it locally (docker is a good idea, if relevant) and where the code's entry point is. 2) Don't use a framework. I don't want to spend time figuring out which of the 20+ code files here have actual code you wrote and which are auto-generated or boilerplate. I'd much rather see something simple but well-written using the language's standard library and a couple well-selected imports than a Twitter clone in Rails or Django or whatever. I certainly don't want a tiny little todo app in a big-ass framework. I won't get upset over it and write you off as a candidate or anything, but you're not gaining many points. 3) You want people to actually engage with what you wrote, spend time on it, and want to talk about it? Don't write a todo app or any of that crap at all. Write a simple game. Put "game" in the title so it shows up in the URL.

dpritchett 9y ago
I failed a interview for a job I'd like to have gotten by trying to impress the reviewers with more handrolled stuff and nothing bloated. I asked and the folks who passed just used Rails. My submission was alternately perceived as underwhelming and trying too hard.
- lgas 9y ago
  Sounds like you dodged a bullet.
andybak 9y ago
> Don't use a framework. I'd like to see people using the appropriate tools for the task at hand. I can imagine slapping my head and asking "Why the hell didn't they just use x". I wouldn't want to pay someone to reinvent the wheel and I'd want someone to demonstrate both their awareness of and their ability to evaluate appropriate code from the relevant ecosystem.
- ashark 9y ago
  It's easy to address that in a readme. "This is a showcase of my craft, for which reason I avoid using frameworks or anything else that would obscure my work with boilerplate or autogenerated code, or anything that's not really mine, though I do rely on others' libraries when it makes sense as those complement and clarify rather than obscure my code. If you just want to see a TODO app I wrote in Rails with a bunch of 3rd party auth via Devise and a Firebase backend and like 100 lines of code that I actually wrote myself, click HERE" [EDIT] tense agreement fix. [EDIT2] misplaced apostrophe
dozzie 9y ago
> 1) Tell me how to run it locally (docker is a good idea, if relevant) [...] Actually no, Docker is not a good idea for an instruction on how to run the code. First, if I don't use Docker, I have no fsckin' way to tell which magical --switches are for Docker and which are for the program. Second, if your program cannot be easily run without Docker, you have vastly overcomplicated the whole thing.
- ashark 9y ago
  It's a hell of a lot better than telling me to install and configure any service dependencies you have (databases, say) outside a container. 'Cuz I'm definitely not going to crap up my system doing that. I'm also not likely to install an entire development environment I don't otherwise need just to run your thing. Just make it a "docker-compose up" for me to install all that junk, or something similarly clean and easy, or it won't happen. Bonus: much higher likelihood that it won't break due to some local environment issue you didn't account for, so lower chance of having your beautiful program fall on its face right out of the gate. Use Vagrant I guess (is that still a thing?) if you're worried about the reviewers not having/wanting Docker or similar, though it's a bigger PITA to configure than Docker and usually takes longer to start up. The point is the concept (keeping your build/run env from crapping up my system in any way that requires me to run more than one or two really easy to discover commands to entirely undo, and ensuring your build/program can run in as many plausible environments as possible without stumbling) not the specific tech. If you don't have any such dependencies (great!), your build environment's really simple, and you're confident the build's reproducible on my machine without containerizing it then don't do that, hence the "if relevant". If you can leave it running on Heroku or something instead that's fine, but documentation-wise the #1 thing I usually want to see, aside from WTF it's for, is a set of instructions (it can be "run 'make && make install'", that's fine, but tell me) for how to build & run the project that actually work if I follow them. That includes programs that run server-side, the authors of which seem to be the worst about not providing such instructions. Even if I don't try it out, seeing credible-looking well-written directions for those most basic of interactions with your project is comforting and will be among the first things I look for. TL;DR the point is your README should prominently contain answers to the questions "how do I build this?" and "how do I run this?" and you should make the answers as painless and easy to undo as possible. [EDIT] and yeah, my fault for not making that TL;DR the entire original statement and avoiding discussion of the not-that-important particulars entirely.

by ashark 9y ago

dpritchett 9y ago

I failed a interview for a job I'd like to have gotten by trying to impress the reviewers with more handrolled stuff and nothing bloated. I asked and the folks who passed just used Rails. My submission was alternately perceived as underwhelming and trying too hard.

lgas 9y ago
Sounds like you dodged a bullet.

andybak 9y ago

> Don't use a framework. I'd like to see people using the appropriate tools for the task at hand. I can imagine slapping my head and asking "Why the hell didn't they just use x". I wouldn't want to pay someone to reinvent the wheel and I'd want someone to demonstrate both their awareness of and their ability to evaluate appropriate code from the relevant ecosystem.

ashark 9y ago
It's easy to address that in a readme. "This is a showcase of my craft, for which reason I avoid using frameworks or anything else that would obscure my work with boilerplate or autogenerated code, or anything that's not really mine, though I do rely on others' libraries when it makes sense as those complement and clarify rather than obscure my code. If you just want to see a TODO app I wrote in Rails with a bunch of 3rd party auth via Devise and a Firebase backend and like 100 lines of code that I actually wrote myself, click HERE" [EDIT] tense agreement fix. [EDIT2] misplaced apostrophe

dozzie 9y ago

> 1) Tell me how to run it locally (docker is a good idea, if relevant) [...] Actually no, Docker is not a good idea for an instruction on how to run the code. First, if I don't use Docker, I have no fsckin' way to tell which magical --switches are for Docker and which are for the program. Second, if your program cannot be easily run without Docker, you have vastly overcomplicated the whole thing.

ashark 9y ago
It's a hell of a lot better than telling me to install and configure any service dependencies you have (databases, say) outside a container. 'Cuz I'm definitely not going to crap up my system doing that. I'm also not likely to install an entire development environment I don't otherwise need just to run your thing. Just make it a "docker-compose up" for me to install all that junk, or something similarly clean and easy, or it won't happen. Bonus: much higher likelihood that it won't break due to some local environment issue you didn't account for, so lower chance of having your beautiful program fall on its face right out of the gate. Use Vagrant I guess (is that still a thing?) if you're worried about the reviewers not having/wanting Docker or similar, though it's a bigger PITA to configure than Docker and usually takes longer to start up. The point is the concept (keeping your build/run env from crapping up my system in any way that requires me to run more than one or two really easy to discover commands to entirely undo, and ensuring your build/program can run in as many plausible environments as possible without stumbling) not the specific tech. If you don't have any such dependencies (great!), your build environment's really simple, and you're confident the build's reproducible on my machine without containerizing it then don't do that, hence the "if relevant". If you can leave it running on Heroku or something instead that's fine, but documentation-wise the #1 thing I usually want to see, aside from WTF it's for, is a set of instructions (it can be "run 'make && make install'", that's fine, but tell me) for how to build & run the project that actually work if I follow them. That includes programs that run server-side, the authors of which seem to be the worst about not providing such instructions. Even if I don't try it out, seeing credible-looking well-written directions for those most basic of interactions with your project is comforting and will be among the first things I look for. TL;DR the point is your README should prominently contain answers to the questions "how do I build this?" and "how do I run this?" and you should make the answers as painless and easy to undo as possible. [EDIT] and yeah, my fault for not making that TL;DR the entire original statement and avoiding discussion of the not-that-important particulars entirely.