查看完整版本: 公司自己的API沒文件
頁: [1]

776556 發表於 2017-7-1 10:57 AM

公司自己的API沒文件

我想問的是,像公司自己寫的API沒有文件,通常會知道有這個API可以用都是某個功能想不出來怎麼寫時,問資深同仁他才說有XXX方法可以使用,不知道其他人也是這樣的模式嗎?
我自己不喜歡這樣,比較喜歡有文件可以看,打一個比喻假設公司自己開發java也用它來寫系統,如果沒有API文件,你String要以(,)這個符號做切割想了半天想不出來,問了資深同事才說有XX方法可以用,不會覺得很幹嗎?
原因1.公司有寫那些功能的API沒文件我哪知道有哪些API可以用
2.如果先問同事有沒有此功能API,每次都要問 那他應該也會覺得很煩吧,因為問10次可能只有2次是可以用公司的API來做其他的還是要自己寫
3.有時自己有寫到方法寫出功能,結果寫完資深同仁一看才在那邊說這個功能公司有API可以用啊(我心裡SO 我哪知道)
4.沒有文件說不定做了5年的資深員工還是有不知道的公司API
5.沒有API文件公司不覺得培養新人新人很沒效率嗎?   
打個比喻2個新人在不同間公司上班
A公司有文件
B公司沒有
這2個新人一開始程式能力都是2好了
過了5年在A公司有文件的功力可能到9
一樣的時間在B公司沒有文件的功力可能只有4
因為時間都浪費掉了
...<div class='locked'><em>瀏覽完整內容,請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div><div></div>

kikuras 發表於 2017-8-4 01:32 AM

台灣做事就是這樣
作文件要時間~你跟老闆或主管給你時間作規格或說明文件...
難啊...

w12463 發表於 2017-11-25 02:44 PM

自己的公司也差不多
重要的系統沒詳細文件  只有應付的文書說明....
老闆能省則省 要做的事情娜麼多又不請人
誰想花時間去做文件?

affkame 發表於 2018-10-27 10:48 PM

這問題其實多數的小公司都有,純粹是規模的問題而已,至於哪間比較好,適合的公司有適合的人

我愛小笨蛋 發表於 2018-11-7 08:13 AM

主要還是要看老闆的觀念
只是一般很多公司文件是不算績效的
所以你花太多時間寫文件結果可能就是老闆覺得你沒績效

有些比較有規模的公司會有把寫文件當成年度績效
所以真的還是要看公司看老闆
<br><br><br><br><br><div></div>

kwj 發表於 2018-11-12 08:32 PM

本帖最後由 kwj 於 2018-11-12 08:38 PM 編輯

其實這要看狀況,如果對於一間數十名工程師一起合作的公司,有 API 文件有可能會有些幫助。但如果到上百人的公司的話,API 文件大概也沒什麼用處了。實務上有很多「人的問題」會導致理想中 API 文件帶來的優點,在人夠多的情況下會完全消失。

舉例來說,十幾二十個人的團隊,基本上每個人之間合作至少還算緊密,遇到需要寫文件時,要統一風格是有點機會。但如果七十人以上的團隊呢?期待團隊中所有人都寫出類似風格的 API 文件是不切實際的。另外如果每個人每一週都能產生一個 API 好了,對於一個七十人的團隊來說,一週會有七十個 API 產生出來,半年就有 1,680 個 API,就算假設裡面有高達 8 成的 API 都是重複的,也會有 336 個不同的 API 被產生出來。你真的確定你能夠了解這所有 336 個半年內產生的 API 嗎?兩年後會增加到上千個,到時你還能了解嗎?在上千個 API 文件中,你有信心能夠找到你想要找的 API 嗎?而且是在很有可能每個人的文件寫作風格都有些不同的情況下(例如有些人用字不精準、或者用字太精準、或者用詞跟別人不同、.....)?

最終來說,的確有 API 文件是好的,因為這樣過去別人做過的東西就可以不用再做一次,不過不用太期待它會解決所有的問題。實務上 API 文件只能幫忙解決少數的程式碼重複而已,而且通常這種能夠被解決的重複,要嘛是功能本身很小(要重寫它只需要一點點時間)、要嘛是功能大/重要到公司幾乎不太會有人不知道。

另外其實個人不認為有 API 文件的新人,能力會成長比較快。實際上我反而覺得有 API 文件的新人,能力很可能成長會比較慢。因為用別人做好的 API 不需要做太多思考,反正 API 就幫你做好它宣稱會做好的事;但自己要寫同樣的 API 卻需要很多思考和練習的過程。...<div class='locked'><em>瀏覽完整內容,請先 <a href='member.php?mod=register'>註冊</a> 或 <a href='javascript:;' onclick="lsSubmit()">登入會員</a></em></div>

xizhao 發表於 2019-1-3 08:58 AM

不意外,可以先將部分的程式碼看過一次之後再盡量用自己的方法配合,另外註解多加一點自成格式,這是我的建議

a9747a 發表於 2019-1-22 05:20 PM

前輩或主管手上應該會有文件吧 不然只能自己摸索了

kcah 發表於 2019-3-19 01:05 PM

最好是你的客戶要求 api 文件...

就算是公司裏面部門跟部門之間 也可以算是客戶關系...

有 api 文件 客戶安心, 你自己也安一點心...

要不然只能爬代碼了...

我們公司用 doxygen... 來寫文件... 不知道適不適用...

Jeepluo 發表於 2019-4-15 09:49 AM

kikuras 說的是,通常老闆都只給程式開發時間,沒有做文件時間
如果你是賣api的,老闆才會給你時間寫,因為客戶要。<br><br><br><br><br><div></div>

ohio1412 發表於 2019-6-21 02:01 AM

我的習慣是沒寫文件的通通電爆,
不適合新人使用就是了。

上面有人提到了一些問題,但事實上問題在主管身上啊,
最好是主管不會去管這些,不要遇到一個廢物主管就以為所有主管都是廢物。
(頂多台灣有七八成是這種的,那就要怪你自已為什麼找不到、進不去那其他二三成的公司)

gooledh 發表於 2019-8-15 11:18 AM

這很正常,完全不意外,也沒什麼
台灣的工作環境就是
老闆要求都是快
相對的下面能省事就省事

jyhfeng 發表於 2020-1-19 10:09 PM

看老闆給你多少時間
你就做多少事情
真的沒事做再來寫吧{:35:}

stephenwei_lu 發表於 2020-2-21 11:41 AM

一是沒有人在規劃這些事, 說白了這是主管的工作, 或者這是主管要分配的工作

就算function寫了說明,一個系統架構本身就不小,誰會吃飽沒事花時間去看funciton.

因為這種工對外沒有績效, 所以才需要某些機制(平台,軟體)讓大家知道自己團隊的每個人都在做什麼

要做的事情列出來, team的人自己認領,又或者指派, 建立KPI. 這樣才能變成一個良好的循環.


ok292 發表於 2020-7-25 01:28 PM

技術不困難~卻有很多人都想暗蓋技術~台灣或ˋ只要是人都這樣的ˊ<br><br><br><br><br><div></div>
頁: [1]