search

exercism / elixir-analyzer

GNU Affero General Public License v3.0
31 stars 32 forks source link

Write analysis for concept exercise `take-a-number` #201

Closed angelikatyborska closed 3 years ago

angelikatyborska commented 3 years ago

Desired checks

Helper function should be private

Look for all the public functions defined in the solution. There should only be one, start/0. Every other function should be private. This should either be an "actionable" or even "informative" comment.

Implementation?

There is no helper macro for this kind of check. It would need to be a custom check directly on the AST using check_source/check.

I'm thinking that I would want this kind of check for almost every exercise. There could be a few different ways to achieve it.

  1. We could have a helper macro "ensure no other public function" which would accept a list of function names/arities and return a comment if it finds more public functions that those on the list. This would be a more manual approach. It would require calling this macro for every exercise.
  2. We could have a common check that loads the exemplar/example solution and gets the list of "allowed" public functions from there. Any public function in the student's solution that's not in the exemplar/example should have been a private function.

@neenjaw @jiegillet ideas, thoughts?

jiegillet commented 3 years ago

Option 2 is way cooler, and I'd totally be up for implementing it :) What I'm not sure is if it's not a little to preachy as a common check, but I'll leave that up to you

angelikatyborska commented 3 years ago

What I'm not sure is if it's not a little to preachy as a common check, but I'll leave that up to you

Hmm. Maybe we should ask some of the mentors. I always tell students to make private everything that doesn't have to be public, but I wouldn't be surprised to be labelled preachy 🙃

angelikatyborska commented 3 years ago

A few voices on Slack agreed with the check.

There was also a mention about @doc false which is a way to hide public functions from the generated documentation. This is necessary when writing a library, and you need to make a function public for your own usage between modules, but the users of your library shouldn't use it.

jiegillet commented 3 years ago

Alright, then if it's OK, I'll assign myself to the task. Since we need to read practice exercise solutions (now we only read concept ones), there are some things that I want to generalize.

There was also a mention about @doc false which is a way to hide public functions from the generated documentation. This is necessary when writing a library, and you need to make a function public for your own usage between modules, but the users of your library shouldn't use it.

I will add a brief explanation about that in the comment.
This kind of check is great, because learning about idiomatic use and advanced tips like this while learning the language is very useful, I think.