문서보다 예제를 선호하십시오. 행동상의 문제입니까?


23

새로운 API 나 프로그래밍 언어, 심지어 간단한 리눅스 매뉴얼 페이지를 접할 때마다 나는 항상 (기억 한 이후) 그것들을 피하고 대신 새로운 개념에 대한 이해를 얻기 위해 예제에 게으르게 의존했다.

무의식적으로, 나는 간단하지 않거나 비밀스럽지 않거나 평범한 지루하지 않을 때마다 문서 / API를 피합니다. 프로그래밍을 시작한 지 몇 년이 지났지 만 이제는 공식 / 예제보다 백만 배나 더 낫기 때문에 암호 / 어려운 문서를 읽는 것을 자제함으로써 더 많은 피해를 입히고 있음을 깨달았으므로 이제 내 방식을 수정해야 할 것 같습니다. 문서는 그 어떤 예보다 더 많은 내용을 담고 있습니다. 그 예가 학습의 "기본"소스 대신 "추가 된"값으로 취급되어야한다는 것을 깨달은 후에도.

프로그래머로서이 나쁜 습관을 어떻게 깨 뜨리나요?


3
나는 그것이 나쁜 습관이라고 생각하지 않습니다. 나는 항상 예제로 시작한 다음 필요에 따라 설명서를 읽습니다.
kaptan

1
a million times better than examples as the official documentation has more coverage-항상 그런 것은 아니지만 예를 통해 과거에 문서화되지 않은 훌륭한 기능을 발견했습니다.
Izkata

문서는 개념을 예제와 통신해야합니다. 나는 일반적으로 문서화에 실패 하지 않은 문서를 고려 합니다.
svidgen

답변:


30

예제를 선호하는 습관은 아무 문제가 없습니다. 답을 얻는 가장 빠른 방법입니다. 또한 예제는 시각적입니다. 텍스트 단락을 읽고 필요한 정보를 추출하는 것보다 시각적으로 예제를 구문 분석하는 것이 더 쉽습니다.

예:

제품을 나열하려면 여기서 가능한 유일한 동사 Index인 경우 Products컨트롤러 GET의 조치를 사용해야합니다 (데이터베이스에서 제품을 작성, 수정 및 삭제하는 데 사용되는 조치에 대한 자세한 정보는 [영향 제품] 참조).

특정 제품에 대한 자세한 정보를 얻으려면 고유 한 식별자를 URI 끝에 추가하십시오. 사용 가능한 모든 제품 목록을 얻으려면 아무 것도 추가하지 마십시오. 매뉴얼의 [데이터 선택을위한 REST 필터] 섹션에 설명 된대로 필터를 사용할 수도 있습니다. 제품 목록은 1,000 개 항목으로 제한됩니다. 각 페이지가 여전히 1,000 개의 항목으로 제한되어 있으면 [Pagination]을 사용하여 전체 목록을 탐색 할 수 있습니다.

서비스에서 재고 수량을 새로 고치도록 강제 할 수도 있습니다. 이를로 설정하면 refresh-quantities됩니다.

상세하지만 지루하고 거의 읽을 수 없습니다. 링크를 따라야한다는 사실은 상황을 더욱 악화시킵니다. 샘플을 추가하면 이해하기가 훨씬 쉬워집니다.

GET 제품 / 인덱스 /
GET 제품 / 인덱스 / 12345 /
GET 제품 / 인덱스 /? skip = 100 & take = 20
GET 제품 / 인덱스 /? category = 12
GET 제품 / 인덱스 /?price=0..39.90
GET 제품 / 인덱스 /? category = 12 & skip = 100 & take = 20

예제 만 사용한다는 사실이 문제가 될 수 있습니다. 예제 사용을 중단하지 말고 일단 아이디어를 얻은 후에는 더 자세한 문서가 도움이 될 수 있습니다. 예를 들어, 위의 샘플은 제품 목록이 1,000 개로 제한되어 있음을 보여주지 않습니다. 해당 문서를 읽어야합니다.

언제 문서를 읽어야하는지 알고 있습니까?

API 또는 라이브러리가 예상대로 작동하지 않을 때마다 예를 들어, 샘플을 잡고 다음을 수행하십시오.

GET 제품 / 색인 /? 건너 뛰기 = 6000 & take = 3000

어떤 이유로 든, 데이터베이스에 2 만 개가 넘는 제품이있는 동안 3 000 개 미만의 항목을 반환합니다. 같은 여기에, API가 작동하지 않는 당신이 예상, 그래서 자세한 문서를 읽을 수있는 좋은 시간입니다.


완벽하게 이해됩니다. 방법이 예제로 포장되어 있어도 항상 문서로 돌아가십시오!
user6123723

2
또한 때로는 결코 찾을 수없는 문서를 철저히 읽음으로써 실제로 간단하고 우아하고 쉬운 방법을 찾을 수 있습니다. 유스 케이스가 없어야합니다).
Amy Blankenship

10

설명서에서 제공하는 정보는 세 가지 범주로 나뉩니다.

  • 레시피.
  • 참고.
  • 전문가 지식.

레시피 나 예제는 문제 영역과 소프트웨어 기능을 연결합니다. 참조는 일부 기능을 완전히 설명하며 레시피를 특정 사례에 적용하려는 경우 유용합니다.

(전문가 지식은 문제 영역의 개념을 문서의 개념에 매핑합니다. 개념을 여러 방식으로 표현할 수 있거나 소프트웨어 사용자가 해당 분야의 전문가가 아닌 경우 유용합니다.)

프로그래머로서이 나쁜 습관을 어떻게 깰 수 있습니까? 동료 프로그래머의 모든 지혜에 감사드립니다.

나는 당신의 습관이 나쁘다고 생각하지 않습니다. API를 배우면 먼저 레시피 (예제)를 통해 어떤 문제를 해결할 수 있고 어떤 방법론이 제공되는지 알 수 있습니다. 그런 다음 참조 문서를 통해 방법론을 특수한 경우에 맞게 미세 조정할 수 있습니다.


3
공룡 시대에 모든 프로그램이 전문적으로 작성된 문서를 인쇄했을 때 일반적으로 참고 설명서와 사용자 안내서라는 두 권의 책이있었습니다. 참조 매뉴얼은 모든 작업에 대한 결정적인 사양이며 사용 설명서는 사용 사례 모음입니다. 둘 다 중요하고 유용했습니다.
로스 패터슨 1

2

예는 문서입니다. API 관점에 익숙해지는 것이 나쁘지 않다고 생각합니다. 당신이 보는 유일한 문서라면 문제가 될 수 있습니다. 대부분의 예제는 오류 검사가 생략되어 참조 문서에서 누락 된 조각을 가져 가지 않으면 코드가 과도하게 부서지기 쉽습니다.


대단해 저의 주요 관심사는 예제에서 파생 된 지식 만 사용한다는 것입니다. 문서에 더 많은 가치가 있기 때문에 그것을 읽지 못하면 그것을 사용하지 못합니다. 문제를 이해 했으므로 이제 더 심각하게 고려해야합니다.
user6123723

1

다른 사람들은 다른 방법으로 더 잘 배웁니다. 어떤 사람들은 당신과 같고 모범을 통해 더 잘 배웁니다. 어떤 사람들은 나와 같아서 자세한 문서를 통해 더 잘 배웁니다. 설명서에 두 가지가 모두 있으면 대부분의 개발자를 잘 다루는 것 같습니다. 교사와 대화하면 사람들이 배우는 십여 가지 방법을 알려줄 수 있습니다.

당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.