[gargarplex]

As a recruiter I can answer this! I do not speak for all recruiters. As a recruiter who is also a programmer, my approach may be nonstandard.

* I want to see thoughtful README files. If the README is whatever was generated default by the framework and not edited at all, that's a huge groan and turn off and you lose tons of strength (credibility) as a candidate.

* I want to see your code looking pretty. Consistent indentation, run through a linter, good comments, and so forth. Would I be able to contribute to and maintain this code?

That's pretty much it. The most important thing that companies want to see is employment history, either at brand name companies or somewhere where you've already been doing the job they're hiring for.

[grepthisab]

This is awful, no offense. You're a recruiter, do you mind if I ask if you were previously a professional software engineer? GitHub is often, very often, for small personal projects where you don't spend a lot of time going through TDD or making sure the readme is up to date. Often mine are smaller projects I built to accomplish a specific goal (hello python script that clicks the "okay I'm still watching" button on all the required learning videos I've had to watch at work). It's impressive when someone has a substantial project or contributed to open source, but GitHub shouldn't be a negative signal.

[Aeolun]

I really don’t see why these things are relevant at all.

It’s a personal Github profile. Why would anyone add thoughtful readme’s or a clean coding style if they’re the only contributor?

I mean, those things are great of course, but not sure if I’d expect it on Github.

[BjoernKW]

If you use your GitHub profile as part of your personal brand / marketing then these things absolutely are relevant.

As a developer in a professional context you'll hardly ever work alone or be the sole contributor.

Even if you use a GitHub profile just as your personal code repository code still is communication, even if it's just with your future self.

Therefore communication skills are crucial. A well-thought-out README file and consistent, readable code help others to understand your work. These aspects often are more important than what the code accomplishes.

Working, even efficient, but unmaintainable code is a risk. Ultimately, code is a precise specification of what the software at hand is supposed to do. If that specification is hard to understand it'll be much less useful.

[RussianCow]

> If you use your GitHub profile as part of your personal brand / marketing then these things absolutely are relevant.

The problem is when others assume this on your behalf. I would take a lack of proper readme as a signal that the repo isn't intended for viewing and judgement by others, not as a signal that the candidate has poor communication skills. If the repo is for a library that the author has published and is marketing for production use, then sure, but I'd wager that does not represent the vast majority of repos on GitHub, and to assume otherwise is foolish in my opinion.

[peruvian]

I use to think this way then I started working in the real world with developers who coded and documented work code cleanly but had messy GitHub profiles especially because until recently private repos were not free. A lot of people don't care about perfectly formatted READMEs, commit comments, etc. if they're just hacking on the weekend on something small... and that's fine.

Nowadays unless you pushed your profile and repos hard in the resume or interview process, I couldn't care less if the rest of the interview went fine. Worst case scenario they're "forced" to write good documentation as part of the job - not everything we do at work is natural or fun for us.

[seba_dos1]

My GitHub/GitLab profiles are full of hacky, ugly games written at game jams in 48 hours, often just by me or me plus some artist, with just one end-goal: to be able to present it at the end of the event. A README file is the last thing needed there :P

[solarkraft]

I 100% disagree. Even just saying that it was hacked together gives some context for

1) Why the code looks so unconventional

2) What you do in your spare time.

[akerl_]

Context for whom? My target audience for my personal projects is myself. Any company that assumes their recruiting org is the target audience for my personal projects is setting themselves up for disappointment.

[yjftsjthsd-h]

Sure, but we're in a discussion of what recruiters look for. If you only code something for yourself, that's fine, but if you want it to be taken well when job-hunting, you should make it at least minimally presentable (i.e., a recruiter can tell what they're even looking at).

[TheRealPomax]

in which case you wouldn't have put your github profile on your resume, so there is no issue. That's not what this question was about, thought.

[chillacy]

Tell us in the readme if you make it public. You gotta think, who is reading this? That goes beyond documentation to code itself and any communication you do.

[godelski]

Repositories are public for a lot of reasons, a lot of which are not "I want to show this off to a potential employer". Let me give some good reasons, that's not an exhaustive list.

- It is the default.

- Free private repos are new and no one is going back and making things private.

- If you are working with someone it is many times easier to make it public.

- You want to share code with someone, public is easier than making them a collaborator.

Honestly I don't think a lot of people, if any, are reading the stuff I have on GitHub.

[seba_dos1]

Of course, I can talk about that. Pointing it out in the README file during the game jam would be the worst use of time available there, though, and even now I have better use of my time than adding it to all of my past ~50 projects like that.

This profile is my personal space where I can put any junk I want to. When you're a recruiter randomly looking at that profile, you won't know the context. If you want to know the context, ask about it. It's not my responsibility to provide it in my personal space.

(plus, what I do in my spare time is the last thing the recruiter should be interested in, unless I mention it to them myself)

[closeparen]

Personal projects can give signal about someone's interests, level of investment, sense of adventure, etc. They're also often an explicit relief valve from "dotting the Is and crossing the Ts" at work, so not a great way to assess professional/production code quality.

If I see a tower of inscrutable Haskell on someone's Github, that is a great thing: both that they have the urge to do it, and the good sense to scratch that itch away from the company's codebase.

[systematical]

I write verbose readme files with examples of how to use my libraries because it's what I expect of other engineers. I do the same for private repos.

[david-s]

Some use GitHub as a portfolio, it seems. Mine is/was mostly a dumping ground of half finished ideas in my college days.

[stevekemp]

The assumption is that if you have a personal github project then you're doing it because it interests you, you're passionate about it, and you're not doing it just for money.

If a developer writes sloppy code when they're doing it for passion, then that doesn't show them at their best. Of course we all have repositories, tools, or code, that was just thrown together to solve an immediate project but in general I'd expect something that is a labour of love - not a project for work - to be something that they'd put more effort into.

[hacym]

You're right -- if they don't feel like they need to have clean, maintainable code on their own personal work, why would they feel like they need to do it at work? That's a red flag.

[k__]

Yes, sounds like BS to me.

But on the other hand I'm no employee and don't know the "virtues" employers look for, haha.

[your-nanny]

if you are linking to it in your resume than you are showcasing it. if you are showcasing it and it's a scrapheap, folks straight not going to be impressed.

I think the obvious thing to do is create a showcase profile and a scrappy scratchpad profile. keep the former clean and polished

[ModernMech]

Ostensibly, you put your code on Github for others to read, use, and maybe even contribute to. If you have a project that you didn't care enough to write cleanly, or even document in the most bare minimum of ways (a helpful README to contextualize the code) then why are you even putting it online? It's just going to reflect poorly upon you. If all your Github repos are as described above, people are going to (rightly) assume that's how you treat all of your projects, even those you are paid for.

[cimmanom]

That’s quite an assumption to make about intentions. Repository hosting is also a way to back up your code or make sure it’s available on multiple devices. Until very recently, you couldn’t do that and keep your code private on github without paying. So (unless they want to also maintain a bitbucket account) people dump stuff there for reasons other than explicitly wanting to share it with the world or show it off.

[ModernMech]

> Until very recently, you couldn’t do that and keep your code private on github without paying.

Ok, but now you can.

> people dump stuff there for reasons other than explicitly wanting to share it with the world or show it off.

Maybe, but that doesn't change the fact you are sharing it with the world and you are showing it off, and if you put a bunch of sloppy inscrutable code on your GitHub, people are going to assume you tend to write sloppy inscrutable code, especially if you don't contextualize it with a Readme. That's just the reality of it. The real big assumption here is thinking people aren't going to judge you by how you present your work online.

[zrobotics]

>>a bunch of sloppy inscrutable code on your GitHub, people are going to assume you tend to write sloppy inscrutable code

Im sorry, but wouldn't most developers have a large amount of code that fits this description? I likely have several mB of hacked python and bash scripts that were only intended to run once. But, I kept them in a repo because I occasionally would refer to an old script. But expecting a readme is a bit much, most of those scripts were lucky to get a descriptive file name, much less documentation. I hate doing documentation professionally, I'm certainly not stressing over it in my free time.

[ModernMech]

This kind of proves the point -- that if a recruiter is looking for a developer who values documentation, the state of documentation on a developer's GitHub is informative.

Personally one thing I've learned over the years is when it comes to referring to old code, having spent a few minutes writing out a description on how to run and configure it is a net time saver in the long run.

[Aeolun]

> That's just the reality of it.

Given that I don’t, and am in a position to hire people tells me this isn’t as hard and fast as you present it.

[ModernMech]

This whole thread started because people claim that they do exactly what I'm describing. I'm not telling you it happens, they are. Just because you don't doesn't mean others do don't as well.

[uiri]

I've been programming for years and I've had a GitHub account for about as long. Almost every piece of code I've ever written that wasn't for an employer or a school assignment has gone into a public GitHub repository. It goes online because that's what I do. It's the easiest way for me to share code with friends and others, to manage it across multiple machines, etc. There's no reason to put it in a private repository, especially if I'm sticking an open source license with a disclaimer like this attached:

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

[ModernMech]

That's well and good, but the thing people seem to keep missing is that git != github. Github is first and foremost a social network. You may keep your personal projects there, but they are still public and on a social network, and that means anyone who reads them will judge them.

The question before us is, how do recruiters judge them?, and the answer one has given is he or she looks at style and clarity in code. Others have come back responding that's not fair or relevant, but that's the reality of putting things into the public sphere; you are judged whether you like it or not on terms that you don't get to dictate.

Look at it this way: when you go out and about to meet someone, you might get all gussied up to present yourself in the best way. But when you go to the grocery store, you might not have done your hair and makeup, maybe you might be wearing day old sweat pants. If someone catches your eye at the grocery store when you're looking like a slob, your chances don't improve just because you put your best foot forward last week at the club.

[nukeop]

It usually takes a lot of work to get a person to judge your work. Typically if you make a repository public, no one will give a shit. It takes a lot of advertising to produce any interest.

I have a repository with 4500 stars, and hundreds of thousands of visitors. Not one person has ever commented on the quality of my code, but many people contribute. Back when I had 100-200 stars, potential employers were impressed by the popularity and rarely commented on the code either. When I got any comments at all, it would be questions like why did I decide to do something one way and not another. No judgment there either.

Bottom line: nobody will ever judge your code if it's public, unless you work very very hard for it.

[ModernMech]

> nobody will ever judge your code if it's public, unless you work very very hard for it.

But this whole thread is about people reporting that they do just that for recruiting purposes.

[uiri]

I was responding to this question:

If you have a project that you didn't care enough to write cleanly, or even document in the most bare minimum of ways (a helpful README to contextualize the code) then why are you even putting it online?

If I put it online for a different intended audience then the question "how do recruiters judge them?" is beside the point.

I am well aware of the difference between git and GitHub. I alluded to some projects that I don't put on GitHub. Let me be explicit in stating that just because the project isn't on GitHub doesn't mean that I don't keep it in a git repository (or other version control, for certain employers). This has nothing to do with confusing git and GitHub.

[wolco]

Looks like someone spends a lot of time on his github profile. Has that made a difference in your job search?

[Novashi]

>that's a huge groan and turn off and you lose tons of strength (credibility) as a candidate.

Toxic and off putting. You put too much weight on relatively minor things. It’s preventing you from fairly considering the rest of the candidate. You could be the one to teach them to do READMEs well.

[beardedwizard]

Wow. This comment is deep. People who call themselves managers, read that last sentence 20x. This is what we need to do, can you?

[chillacy]

Most big companies no longer believe in training but selecting. This is popularized in “strengths based” training sold by a handful of consultants.

[zepolen]

So choose between:

1. A developer who doesn't respect himself first and foremost to write a README/maintainable code so that his future self and others can have an easier time.

2. A developer who cares about communicating his work to himself/others and making the environment easier for everyone to work for the future.

Right.

[Novashi]

False dichotomy, and if you actually witness this first hand and only have two options in your candidate pool, you might need to spread your net a bit further. Also the original post was about READMEs only, so if they have unmaintainable code, the README really doesn't matter that much, does it?

Developers are at various stages in their expertise when they go looking for jobs. READMEs are nice but try not to let yourself get tied up with emphasis on a few signals that document the whole human. README quality is a pretty weak signal.

If you bring up the README in an interview, and the dev cannot find any motivation or acknowledge that it could be better, then maybe you might have to pass on them. My problem with your methods is that you get to this point without even opening a discussion.

READMEs are a relatively teach-able skill and in pretty quick fashion. Maintainable code, much less so obviously.

[zepolen]

> README quality is a pretty weak signal.

It's a fantastic signal of what the quality of the code will be. Lack of a README indicates many things, including unmaintainable code either via lack of experience or rushed work.

But hey talk is cheap and you seem to know a lot - so how about you link an open source project you've published ;)

[dang]

That crosses into personal attack, which is a bannable offense on HN. Please don't do this.

https://news.ycombinator.com/newsguidelines.html

[Novashi]

>But hey talk is cheap and you seem to know a lot - so how about you link an open source project you've published ;)

I wrote tech docs explaining the jungle of IT systems that we were relying on at a hospital I worked at, and sometimes that included diving into old code. These were usually much longer than READMEs.

Having a README wouldn't have saved this code from needing to be refactored. Nor would it have really changed my opinion of the code. It hasn't been a reliable signal.

The hard part about documentation is keeping it up-to-date and accurate and not filling it with extraneous details and going off on tangents. A lot of the READMEs are written for quick bootstrapping and that isn't going to reflect much on your code quality. I care more about good documentation and that's harder to write than a README and a much better signal.

I don't have time to work on open source but it's clear my experience has been vastly different than yours and I doubt either one of us are going to come up with a peer reviewed reason for either side.

Turn this around and say "this repo has a README! surely it's really good and so is the code" and it makes no sense to give that much credit for something that really isn't impactful beyond the first few days of using something.

[zepolen]

A programmer who by default adds a good concise readme to his projects is an indicator that the same will apply to the codebase, in that he will plan for the future.

I've seen it too many times, exceptions are rare.

A good readme is concise, it offers key 'bring me up to speed as fast as possible' information, nothing more. It's not documentation.

A good readme should include a quick bootstrapping info, but it's not enough, it should have a concise summary overview and list any important gotchas. As well as provide the procedures for builds/releases if apply. Links to relevant docs if exist are fine if the information becomes too large for the readme.

> Having a README wouldn't have saved this code from needing to be refactored. Nor would it have really changed my opinion of the code. It hasn't been a reliable signal.

See I read that and figure that it was actually a perfect signal - since that "bad unmaintainable code" lacked a good readme.

It's like the Van Halen requiring Brown M&Ms at their concerts https://www.snopes.com/fact-check/brown-out/ - I've found the README is one of the best indicators of the level of detail a person applies to their work.

> it makes no sense to give that much credit for something that really isn't impactful beyond the first few days of using something.

This is the attitude that I wouldn't be looking for when recruiting - a README has a ton of use, for helping bootstrapping new people to the code base - to even helping yourself if you do some maintenance on an old project and don't want to spend more than the minimum time necessary.

It's this forethought I'd like to see in a candidate, and that 99.9% of the time shows in the quality of the readme.

[chickenfries]

I cannot stand this kind of developer armchair psychology.

[amitport]

You're choosing between a person who didn't write a readme and a person who did.

Anything beyond that is unfounded bias IMHO.

(I have a lot of personal projects and I've conducted interviews)

[beardedwizard]

Are developers only male? Your biases are really showing in these comments.

[bjourne]

I don't agree with zepolen's comments at all. But can you guys who use "downvote to disagree" kindly please stop? You are just making Ask HN worse for all of us by turning it into an echo chamber. This isn't Reddit FFS.

[zepolen]

In the long term any vote based community turns into an echo chamber.

The popular opinions win.

The users with unpopular opinions get downvoted/censored and are either banned/leave.

Leaving one opinion behind.

Moderators also a play a huge part in this - which is why it's only an illusion of democracy.

I wonder if it would be possible to create truly neutral discussion platform that doesn't end up as an echo chamber.

[yeahitslikethat]

And fading out comments just because people here disagree with them is super annoying.

If 4 ppl disagree with something No one else is even able read it??

We shall all only say that which no one will disagree with.

[gherlein]

That's lame, sorry. As a long-time hiring manager I do value a good readme if the project is meant for others to consume, otherwise if it's a scratch pad for learning who cares? And I could care less about how pretty their code is. I'm more interested to see if they are PASSIONATE about tech. While it's true that some folks don't have time outside of work my experience is that really good Engineers still play around a bit. They fork stuff. They try it. They may submit a PR that fixes something. They have some experimental repos where they put stuff when learning a new language. And yes, the rare one will have a fork of a project where they regularly contribute. I don't think you are looking for the things I look for in a candidate at all.

[avip]

Let me politely call BS on that. There is no possible correlation between the "code quality" of my random github repos, which I usually start to learn/test/share something, and my general ability to write clean documented code. If a project evolves to have users, things shift.

[iandanforth]

I know people are being down on this comment, but it's important to know that people do this, which might help people get jobs.

Google is known to can applications if there are typos in either the resume or cover letter. Supposedly there is a statistical correlation that backs this. While this seems arbitrary and absurd it is important to know it's a thing so you can at least work around it.

[projektir]

I disagree. Bending over backwards to strange expectations and requirements is a race to the bottom.

[Waterluvian]

Everything you say makes sense on the surface. But it scares me a little bit.

Do you ignore all my half-done prototypes and junky hacks and experiments?

[Frost1x]

Or your proprietary work you don't own IP to. Ironically, some look to GitHub to somehow correlate with employment history. Many employed are too busy sinking development time in source that's never releasable. Some companies may contribute to certain OSS projects publically but a lot of their core business code base is protected.

[Benjammer]

This is what I never understood. Say that I choose to spend my spare time in propriety code instead of open source or personal hobby code. It seems like some recruiters are making a tradeoff in indicating metrics here. They are saying that a good GitHub profile correlates so strongly with a good recruit, that it's worth a false positive of someone who spends too much time working on side projects and doesn't get as much done at work, and also this seems to be saying that people who spend spare time innovating proprietary code aren't worth finding and should be lumped into the weak coder pile by default. Is this a plausible deniability thing? ("How could I have known that guy would be a dud? I mean, look at his GH!"). This can't possibly correlate as well as people claim to success on the job... There just seem to me to be too many other complicating factors for this specifically to be any kind of decent metric.

[jordache]

Haha dude expects personal projects to go through a linter... You code?